Update README.md

README.md

@@ -1,21 +1,184 @@
 ---
-base_model: unsloth/gemma-3-1b-it-unsloth-bnb-4bit
-tags:
-- text-generation-inference
-- transformers
-- unsloth
-- gemma3_text
-license: apache-2.0
 language:
 - en
+license: gemma
+base_model: google/gemma-3-1b-it
+tags:
+- text-classification
+- email-classification
+- fine-tuned
+- unsloth
+- lora
+- qlora
+- gemma
+- causal-lm
+datasets:
+- response-classification-dataset
+pipeline_tag: text-generation
+library_name: vllm
+---
+
+# 📧 Customer Email Response Classifier
+
+Fine-tuned **Gemma 3 1B IT** (`google/gemma-3-1b-it`) for classifying customer email responses into 5 categories. The model generates a structured JSON output and is optimized for low-latency deployment via **vLLM**.
+
+## Model Summary
+
+| Property | Value |
+|---|---|
+| **Base model** | `google/gemma-3-1b-it` |
+| **Task** | Generative classification (Causal-LM) |
+| **PEFT method** | QLoRA (4-bit) via Unsloth |
+| **Training framework** | Unsloth `SFTTrainer` with completion-only masking |
+| **Dataset size** | ~3,500 samples |
+| **Output format** | `{"classification": "<label>"}` |
+| **Deployment target** | vLLM (`/v1/chat/completions`) |
+
+---
+
+## Labels
+
+The model classifies each email into exactly one of:
+
+| Label | Description |
+|---|---|
+| `automated_reply` | Auto-generated out-of-office or delivery receipts |
+| `interested` | Recipient shows genuine interest or engagement |
+| `not_interested` | Recipient explicitly declines or opts out |
+| `out_of_office` | Human OOO message (distinct from automated replies) |
+| `unrelated` | Reply does not relate to the original outreach |
+
+---
+
+## Usage
+
+### Transformers (local)
+
+```python
+import json
+import torch
+from transformers import pipeline
+
+LABELS = ["automated_reply", "interested", "not_interested", "out_of_office", "unrelated"]
+SYSTEM_PROMPT = (
+    "You are an email-response classifier. "
+    f"Classify the email into exactly one of: {', '.join(LABELS)}. "
+    'Reply ONLY with a JSON object in the format: {"classification": "<label>"}. '
+    "Do not add any explanation."
+)
+
+gen = pipeline(
+    "text-generation",
+    model="OmarioVIC/customer-email-classifier",
+    device=0 if torch.cuda.is_available() else -1,
+    do_sample=False,
+)
+
+def classify(email_text: str) -> str:
+    messages = [{"role": "user", "content": f"{SYSTEM_PROMPT}\n\nEmail text:\n{email_text}"}]
+    prompt = gen.tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    output = gen(prompt, max_new_tokens=20)
+    generated = output[0]["generated_text"].split("<start_of_turn>model")[-1].strip()
+    return json.loads(generated)["classification"]
+
+print(classify("Yeah, Monday works — book a 15-min call."))
+# → "interested"
+```
+
+### vLLM (recommended for production)
+
+**Serve:**
+```bash
+pip install vllm
+
+vllm serve OmarioVIC/customer-email-classifier \
+    --dtype bfloat16 \
+    --max-model-len 512
+```
+
+**Query:**
+```bash
+curl http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "OmarioVIC/customer-email-classifier",
+    "messages": [{
+      "role": "user",
+      "content": "Classify into one of: automated_reply, interested, not_interested, out_of_office, unrelated. Reply with JSON only: {\"classification\": \"<label>\"}.\n\nEmail text:\nyeah 15 mins call? free monday"
+    }],
+    "max_tokens": 20,
+    "temperature": 0
+  }'
+```
+
 ---
 
-# Uploaded finetuned  model
+## Training Details
+
+### Data Format
+
+Each training example is a chat-template conversation:
+
+```json
+{
+  "messages": [
+    {
+      "role": "user",
+      "content": "<system prompt>\n\nEmail text:\n<raw email body>"
+    },
+    {
+      "role": "assistant",
+      "content": "{\"classification\": \"interested\"}"
+    }
+  ]
+}
+```
+
+Only the assistant turn is used for loss computation (completion-only masking via `train_on_responses_only`).
+
+### Hyperparameters
+
+| Parameter | Value |
+|---|---|
+| Epochs | 3 |
+| Batch size (per device) | 4 |
+| Gradient accumulation steps | 4 |
+| Learning rate | 2e-4 |
+| LR scheduler | Cosine |
+| Warmup steps | 50 |
+| Max sequence length | 320 |
+| Precision | bfloat16 (Ampere+) / float16 |
+
+### LoRA Config
 
-- **Developed by:** OmarioVIC
-- **License:** apache-2.0
-- **Finetuned from model :** unsloth/gemma-3-1b-it-unsloth-bnb-4bit
+| Parameter | Value |
+|---|---|
+| Rank (`r`) | 32 |
+| Alpha | 32 |
+| Dropout | 0.05 |
+| Target modules | All linear layers |
+| Gradient checkpointing | Unsloth optimised |
+
+---
+
+## Framework
+
+Training was accelerated using [Unsloth](https://github.com/unslothai/unsloth), which provides:
+- **2× faster training** via custom CUDA kernels
+- **~60% less VRAM** via QLoRA 4-bit quantisation
+
+The final model was merged to full 16-bit weights (`merged_16bit`) for straightforward vLLM deployment.
+
+---
+
+## Limitations
+
+- Designed for **short email replies** (max 320 tokens including prompt).
+- Trained on a specific business outreach dataset; may not generalise to all email domains.
+- Output is deterministic (`do_sample=False`, `temperature=0`) — always greedy.
+
+---
 
-This gemma3_text model was trained 2x faster with [Unsloth](https://github.com/unslothai/unsloth) and Huggingface's TRL library.
+## License
 
-[<img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" width="200"/>](https://github.com/unslothai/unsloth)
+This model is derived from `google/gemma-3-1b-it` and is subject to the [Gemma Terms of Use](https://ai.google.dev/gemma/terms).