---
language:
- en
license: apache-2.0
tags:
- text-classification
- indian-names
- gender-prediction
- unsloth
- llama-3
- nlp
- gguf
- lora
base_model: unsloth/llama-3-8b-bnb-4bit
datasets:
- shisha-07/Indian_Names_with_Gender_Dataset
metrics:
- accuracy
- f1
model-index:
- name: Llama-3-Indian-Gender-Classifier
  results:
  - task:
      type: text-classification
    dataset:
      type: custom
      name: shisha-07/Indian_Names_with_Gender_Dataset
    metrics:
    - type: accuracy
      value: 0.8644
    - type: f1
      value: 0.8355
---

# 🇮🇳 Llama-3 Indian Name Gender Classifier

![Unsloth](https://img.shields.io/badge/Unsloth-Fine--Tuning-blue) ![Llama-3](https://img.shields.io/badge/Model-Llama--3--8B-green) ![Task](https://img.shields.io/badge/Task-Gender--Classification-orange) [![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/SHIVASHANKAR-V07/Llama_3_Indian_Gender_Classifier)

## 📖 Model Description
This is a fine-tuned version of the **Llama-3-8B** model, specifically optimized to classify the gender of **Indian Names** into three categories: **Male**, **Female**, and **Neutral**.

The model was trained using [Unsloth](https://github.com/unslothai/unsloth) for efficient 4-bit fine-tuning and has been exported in multiple formats to support both production (Python/GPU) and local (CPU/Laptop) environments.

## 🛠️ Source Code
The training code and notebooks are available on GitHub:
* [Training Notebook](https://github.com/your_username/your_repo_name/blob/main/notebooks/Gender_Classifier_Training.ipynb)

### Key Features
* **High Precision for Females:** The model achieves **100% precision** on female names in validation tests.
* **Regional Awareness:** Trained specifically on Indian linguistic patterns.
* **Multi-Format:** Available as LoRA adapters, Merged 16-bit weights, and GGUF.

---

## 📂 Repository Structure
This repository is organized into three specific folders to keep files clean. **Please select the folder that matches your use case:**

| Folder | Format | Use Case |
| :--- | :--- | :--- |
| **[`/Merged`](./Merged)** | **SafeTensors (16-bit)** | Best for **Python**, **vLLM**, and **Production APIs**. This is the standalone model with weights baked in. |
| **[`/GGUF`](./GGUF)** | **GGUF (q4_k_m)** | Best for **Ollama**, **LM Studio**, and **Local CPU Inference**. |
| **[`/LoRA`](./LoRA)** | **LoRA Adapters** | Best for **Research**, **Unsloth**, and **PEFT** loading. Contains only the fine-tuned difference. |

---

## 📊 Evaluation & Performance
The model was evaluated on a held-out test set of **59 diverse Indian names**, including difficult unisex/neutral examples.

### Summary Metrics
| Metric | Score | Interpretation |
| :--- | :--- | :--- |
| **Accuracy** | **86.44%** | Overall correctness across all categories. |
| **F1-Score** | **0.8355** | Weighted score balancing precision and recall. |

### Detailed Breakdown
| Category | Precision | Recall | F1-Score | Analysis |
| :--- | :--- | :--- | :--- | :--- |
| **Male** | 0.76 | **1.00** | 0.87 | Catches all males, but sometimes over-predicts male for neutral names. |
| **Female** | **1.00** | 0.96 | **0.98** | Extremely reliable. If it says "Female", it is almost certainly correct. |
| **Neutral** | 1.00 | 0.22 | 0.36 | Struggles with ambiguity; often defaults to "Male". |

### ⚠️ Known Limitations & Bias
* **Male Defaulting:** The model has a strong bias to classify ambiguous or neutral names as **Male**.
    * *Failed Examples:* `Kiran`, `Sonu`, `Suman`, `Gurpreet` (Predicted: Male).
* **Specific Mismatches:** The name `Simran` was incorrectly predicted as `Male` in our validation set.
* **Scope:** This model is strictly for **Indian** names and may not perform accurately on Western or East Asian names.

---

## 🚀 How to Use

### 1. Python (Transformers) - *Recommended*
Use this method if you are running a script or a web server. **Note:** You must specify `subfolder="Merged"`.

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# 1. Load from the 'Merged' folder
model_id = "shisha-07/Llama-3-Indian-Gender-Classifier"
tokenizer = AutoTokenizer.from_pretrained(model_id, subfolder="Merged")
model = AutoModelForCausalLM.from_pretrained(
    model_id, 
    subfolder="Merged",
    device_map="auto",
    torch_dtype=torch.float16
)

# 2. Define the Prompt (Alpaca Format)
prompt_template = """### Instruction:
Identify the gender of the given Indian name.

### Input:
{}

### Response:
"""

# 3. Run Inference
name = "Ananya"
inputs = tokenizer(prompt_template.format(name), return_tensors="pt").to("cuda")
output = model.generate(**inputs, max_new_tokens=10)

print(tokenizer.decode(output[0], skip_special_tokens=True))
# Output: Female
```

### 2. GGUF (Ollama / Local) -
Download the `.gguf` file from the **[`GGUF`](./GGUF)** Folder.

- **CLI Command:**

```Bash
./llama-cli -m llama-3-indian-gender.Q4_K_M.gguf -p "### Instruction: Identify the gender. ### Input: Rajesh ### Response:"
```

- **Ollama:** Create a Modelfile with the following content:

```Dockerfile
FROM ./llama-3-indian-gender.Q4_K_M.gguf
TEMPLATE """### Instruction:
Identify the gender of the given Indian name.

### Input:
{{ .Prompt }}

### Response:
"""
```

### 3. LoRA Adapters (Unsloth) -
Use this if you want to load the adapters on top of the base Llama-3 model dynamically.

```python
from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "shisha-07/Llama-3-Indian-Gender-Classifier",
    subfolder = "LoRA", # Specific folder for adapters
    load_in_4bit = True,
)
FastLanguageModel.for_inference(model)

# ... Run inference as usual
```

---

# 🛠️ Training Details
- **Base Architecture:** Llama-3-8B-bnb-4bit

- **Fine-Tuning Method:** QLoRA (via Unsloth)

- **Dataset:** Custom dataset of Indian names labeled by gender.

- **Infrastructure:** Trained on Tesla T4 GPU (Google Colab)

## **📜 License**
Apache-2.0

[<img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" width="200"/>](https://github.com/unslothai/unsloth)