Update README.md

README.md

@@ -35,306 +35,358 @@ model-index:
       value: 4.5
       name: Age MAE (years)
 ---
-
-
-# 🏆 ViT-Age-Gender-Prediction: Vision Transformer for Facial Analysis
+# 🏆 ViT Age-Gender Prediction: Vision Transformer for Facial Analysis
 
 [![Model](https://img.shields.io/badge/Model-Vision%20Transformer-blue)](https://huggingface.co/abhilash88/age-gender-prediction)
 [![Accuracy](https://img.shields.io/badge/Gender%20Accuracy-94.3%25-green)](https://huggingface.co/abhilash88/age-gender-prediction)
-[![Pipeline](https://img.shields.io/badge/Pipeline-Ready-orange)](https://huggingface.co/abhilash88/age-gender-prediction)
+[![Pipeline](https://img.shields.io/badge/Pipeline-One%20Liner-brightgreen)](https://huggingface.co/abhilash88/age-gender-prediction)
+
+A state-of-the-art Vision Transformer model for simultaneous age estimation and gender classification, achieving **94.3% gender accuracy** and **4.5 years age MAE** on the UTKFace dataset.
+
+## 🚀 One-Liner Usage
 
-A state-of-the-art Vision Transformer model for simultaneous age estimation and gender classification, achieving **94.3% gender accuracy** and **4.5 years age MAE**. Now with **Hugging Face Pipeline support** for ultra-easy usage!
+```python
+from transformers import pipeline
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
+result = classifier("your_image.jpg")
+print(f"Age: {result[0]['age']}, Gender: {result[0]['gender']}")
+```
 
-## 🚀 Quick Start (Pipeline - Recommended)
+**That's it!** One line to get age and gender predictions.
 
-### Super Simple Usage
+## 📱 Complete Examples
 
+### Basic Pipeline Usage
 ```python
 from transformers import pipeline
 
-# Create the pipeline (one line!)
-classifier = pipeline("age-gender-classification", model="abhilash88/age-gender-prediction")
+# Create classifier
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
 
-# Predict from image path
-result = classifier("path/to/your/image.jpg")
-print(result)
-# Output: {'age': 25, 'gender': 'Female', 'gender_confidence': 0.892, ...}
+# Predict from file
+result = classifier("your_image.jpg")
+print(f"Age: {result[0]['age']} years")
+print(f"Gender: {result[0]['gender']}")
+print(f"Confidence: {result[0]['gender_confidence']:.1%}")
 
 # Predict from URL
 result = classifier("https://example.com/face_image.jpg")
-print(f"Age: {result['age']}, Gender: {result['gender']} ({result['gender_confidence']:.1%})")
-```
+print(f"Prediction: {result[0]['age']} years, {result[0]['gender']}")
 
-### Even Simpler One-Liner
+# Predict from PIL Image
+from PIL import Image
+img = Image.open("image.jpg")
+result = classifier(img)
+print(f"Result: {result[0]['age']} years, {result[0]['gender']}")
+```
 
+### Simple Helper Functions
 ```python
-from transformers import pipeline
+from model import predict_age_gender, simple_predict
 
-# One-line prediction!
-result = pipeline("age-gender-classification", model="abhilash88/age-gender-prediction")("your_image.jpg")
-print(f"Predicted: {result['age']} years old, {result['gender']}")
-```
+# Method 1: Detailed result
+result = predict_age_gender("your_image.jpg")
+print(f"Age: {result['age']}, Gender: {result['gender']}")
+print(f"Confidence: {result['confidence']:.1%}")
 
-### Batch Processing
+# Method 2: Simple string output
+prediction = simple_predict("your_image.jpg")
+print(prediction)  # "25 years, Female (87% confidence)"
+```
 
+### Google Colab
 ```python
-classifier = pipeline("age-gender-classification", model="abhilash88/age-gender-prediction")
+# Install requirements
+!pip install transformers torch pillow
 
-# Process multiple images at once
-images = ["image1.jpg", "image2.jpg", "image3.jpg"]
-results = classifier(images)
+from transformers import pipeline
+import matplotlib.pyplot as plt
+from PIL import Image
 
-for i, result in enumerate(results):
-    print(f"Image {i+1}: {result['age']} years, {result['gender']}")
-```
+# Create classifier
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
 
-## 🔧 Advanced Usage
+# Upload image in Colab
+from google.colab import files
+uploaded = files.upload()
+filename = list(uploaded.keys())[0]
 
-### Custom Parameters
+# Predict and display
+result = classifier(filename)
+img = Image.open(filename)
+
+plt.figure(figsize=(8, 6))
+plt.imshow(img)
+plt.title(f"Prediction: {result[0]['age']} years, {result[0]['gender']} ({result[0]['gender_confidence']:.1%})")
+plt.axis('off')
+plt.show()
 
+print(f"Age: {result[0]['age']} years")
+print(f"Gender: {result[0]['gender']}")
+print(f"Confidence: {result[0]['gender_confidence']:.1%}")
+```
+
+### Batch Processing
 ```python
-classifier = pipeline("age-gender-classification", model="abhilash88/age-gender-prediction")
+from transformers import pipeline
 
-result = classifier(
-    "image.jpg",
-    confidence_threshold=0.7,  # Custom confidence threshold
-    return_all_scores=True     # Get raw model outputs
-)
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
 
-print(result)
-# Output includes raw probabilities and detailed scores
+# Process multiple images
+images = ["image1.jpg", "image2.jpg", "image3.jpg"]
+results = []
+
+for image in images:
+    result = classifier(image)
+    results.append({
+        'image': image,
+        'age': result[0]['age'],
+        'gender': result[0]['gender'],
+        'confidence': result[0]['gender_confidence']
+    })
+
+for result in results:
+    print(f"{result['image']}: {result['age']} years, {result['gender']} ({result['confidence']:.1%})")
 ```
 
-### Integration with OpenCV/PIL
-
+### Real-time Webcam
 ```python
 import cv2
-from PIL import Image
 from transformers import pipeline
 
-classifier = pipeline("age-gender-classification", model="abhilash88/age-gender-prediction")
-
-# From OpenCV
-img_cv = cv2.imread("image.jpg")
-img_rgb = cv2.cvtColor(img_cv, cv2.COLOR_BGR2RGB)
-result = classifier(img_rgb)
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
 
-# From PIL
-img_pil = Image.open("image.jpg")
-result = classifier(img_pil)
+cap = cv2.VideoCapture(0)
+while True:
+    ret, frame = cap.read()
+    if ret:
+        # Save frame temporarily
+        cv2.imwrite("temp_frame.jpg", frame)
+        
+        # Predict
+        result = classifier("temp_frame.jpg")
+        
+        # Display prediction
+        text = f"Age: {result[0]['age']}, Gender: {result[0]['gender']}"
+        cv2.putText(frame, text, (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+        cv2.imshow('Age-Gender Detection', frame)
+        
+    if cv2.waitKey(1) & 0xFF == ord('q'):
+        break
 
-# From NumPy array
-import numpy as np
-img_array = np.array(img_pil)
-result = classifier(img_array)
+cap.release()
+cv2.destroyAllWindows()
 ```
 
-### Google Colab Example
-
+### URL Images
 ```python
-# Install in Colab
-!pip install transformers torch pillow
-
-# Quick test
 from transformers import pipeline
-import matplotlib.pyplot as plt
-from PIL import Image
 
-# Upload image in Colab and run
-classifier = pipeline("age-gender-classification", model="abhilash88/age-gender-prediction")
-result = classifier("uploaded_image.jpg")
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
 
-# Display result
-img = Image.open("uploaded_image.jpg")
-plt.imshow(img)
-plt.title(f"Predicted: {result['age']} years, {result['gender']} ({result['gender_confidence']:.1%})")
-plt.axis('off')
-plt.show()
+# Direct URL prediction
+image_url = "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=300"
+result = classifier(image_url)
+
+print(f"Age: {result[0]['age']} years")
+print(f"Gender: {result[0]['gender']}")
+print(f"Confidence: {result[0]['gender_confidence']:.1%}")
 ```
 
-## 🎯 Manual Implementation (Alternative)
+## 📊 Pipeline Output Format
 
-If you prefer manual control or need to modify the model:
+The pipeline returns a list with one prediction:
 
 ```python
-import torch
-import torch.nn as nn
-from transformers import ViTImageProcessor, ViTModel
-from PIL import Image
-
-class AgeGenderViTModel(nn.Module):
-    def __init__(self):
-        super().__init__()
-        self.vit = ViTModel.from_pretrained('google/vit-base-patch16-224')
-        self.age_head = nn.Linear(self.vit.config.hidden_size, 1)
-        self.gender_head = nn.Sequential(
-            nn.Linear(self.vit.config.hidden_size, 1),
-            nn.Sigmoid()
-        )
-        
-    def forward(self, pixel_values):
-        outputs = self.vit(pixel_values=pixel_values)
-        pooled_output = outputs.pooler_output
-        age_output = self.age_head(pooled_output)
-        gender_output = self.gender_head(pooled_output)
-        return age_output, gender_output
-
-# Load model manually
-model = AgeGenderViTModel()
-model.load_state_dict(torch.hub.load_state_dict_from_url(
-    "https://huggingface.co/abhilash88/age-gender-prediction/resolve/main/pytorch_model.bin"
-))
-model.eval()
-
-processor = ViTImageProcessor.from_pretrained("google/vit-base-patch16-224")
-
-# Predict
-image = Image.open("your_image.jpg")
-inputs = processor(images=image, return_tensors="pt")
-with torch.no_grad():
-    age_pred, gender_pred = model(inputs["pixel_values"])
-    
-age = int(torch.clamp(age_pred, 0, 100).item())
-gender = "Female" if gender_pred.item() > 0.5 else "Male"
-confidence = gender_pred.item() if gender_pred.item() > 0.5 else 1 - gender_pred.item()
-
-print(f"Age: {age} years, Gender: {gender} ({confidence:.1%})")
+[
+    {
+        "label": "25 years, Female",
+        "score": 0.873,
+        "age": 25,
+        "gender": "Female", 
+        "gender_confidence": 0.873,
+        "gender_probability_female": 0.873,
+        "gender_probability_male": 0.127
+    }
+]
 ```
 
-## 📊 Model Performance
+**Access the values:**
+- `result[0]['age']` - Predicted age (integer)
+- `result[0]['gender']` - Predicted gender ("Male" or "Female")
+- `result[0]['gender_confidence']` - Confidence score (0-1)
+- `result[0]['label']` - Formatted string summary
+
+## 🎯 Model Performance
 
 | Metric | Performance | Dataset |
 |--------|------------|---------|
 | **Gender Accuracy** | **94.3%** | UTKFace |
 | **Age MAE** | **4.5 years** | UTKFace |
-| **Parameters** | 86.8M | ViT-Base |
+| **Architecture** | ViT-Base + Dual Head | 768→256→64→1 |
+| **Parameters** | 86.8M | Optimized |
 | **Inference Speed** | ~50ms/image | CPU |
-| **Pipeline Support** | ✅ Native | Transformers |
 
-### Performance by Demographics
+### Performance by Age Group
+- **Adults (21-60 years)**: 94.3% gender accuracy, 4.5 years age MAE ✅ **Excellent**
+- **Young Adults (16-30 years)**: 92.1% gender accuracy ✅ **Very Good**  
+- **Teenagers (13-20 years)**: 89.7% gender accuracy ✅ **Good**
+- **Children (5-12 years)**: 78.4% gender accuracy ⚠️ **Limited**
+- **Seniors (60+ years)**: 87.2% gender accuracy ✅ **Good**
+
+## ⚠️ Usage Guidelines
+
+### ✅ Optimal Performance
+- **Best for**: Adults 16-60 years old
+- **Image quality**: Clear, well-lit, front-facing faces
+- **Use cases**: Demographic analysis, content filtering, marketing research
 
-| Age Group | Gender Accuracy | Age MAE | Recommendation |
-|-----------|----------------|---------|----------------|
-| **Adults (21-60)** | 94.3% | 4.5 years | ✅ **Excellent** |
-| **Young Adults (16-30)** | 92.1% | 5.2 years | ✅ **Very Good** |
-| **Teenagers (13-20)** | 89.7% | 6.8 years | ✅ **Good** |
-| **Children (5-12)** | 78.4% | 8.9 years | ⚠️ **Limited** |
-| **Seniors (60+)** | 87.2% | 7.1 years | ✅ **Good** |
+### ❌ Known Limitations  
+- **Children (0-12)**: Reduced accuracy due to limited training data
+- **Very elderly (70+)**: Higher prediction variance
+- **Poor conditions**: Low light, extreme angles, heavy occlusion
+
+### 🎯 Tips for Best Results
+- Use clear, well-lit images
+- Ensure faces are clearly visible and front-facing
+- Consider confidence scores for critical applications
+- Validate results for your specific use case
 
-## 🔄 Pipeline vs Manual Usage
+## 🛠️ Installation
+
+```bash
+# Minimal installation
+pip install transformers torch pillow
 
-### ✅ Pipeline Advantages
-- **One-line usage**: Extremely simple API
-- **Auto-downloading**: No manual model loading
-- **Batch processing**: Handle multiple images easily
-- **Type flexibility**: Works with paths, URLs, PIL, NumPy
-- **Error handling**: Built-in robust error management
-- **Future-proof**: Automatic updates with transformers library
+# Full installation with optional dependencies  
+pip install transformers torch torchvision pillow opencv-python matplotlib
 
-### 🔧 Manual Advantages
-- **Full control**: Modify model architecture
-- **Custom preprocessing**: Add your own image processing
-- **Memory efficiency**: Load model once, reuse multiple times
-- **Custom outputs**: Access raw model predictions
-- **Debugging**: Step-through model internals
+# For development
+pip install transformers torch pillow pytest black flake8
+```
 
-## 📈 Usage Examples by Use Case
+## 📈 Use Cases & Examples
 
 ### Content Moderation
 ```python
-classifier = pipeline("age-gender-classification", model="abhilash88/age-gender-prediction")
+from transformers import pipeline
+
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
 
-def moderate_content(image_url):
-    result = classifier(image_url)
-    if result['age'] < 18:
-        return "Minor detected - content flagged"
-    return f"Adult content: {result['gender']}, {result['age']} years"
+def moderate_content(image_path):
+    result = classifier(image_path)
+    age = result[0]['age']
+    
+    if age < 18:
+        return f"Minor detected ({age} years) - content flagged for review"
+    return f"Adult content approved: {age} years, {result[0]['gender']}"
+
+status = moderate_content("user_upload.jpg")
+print(status)
 ```
 
 ### Marketing Analytics
 ```python
-def analyze_audience(image_list):
-    classifier = pipeline("age-gender-classification", model="abhilash88/age-gender-prediction")
-    results = classifier(image_list)
+from transformers import pipeline
+
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
+
+def analyze_audience(image_folder):
+    from glob import glob
+    
+    demographics = {"male": 0, "female": 0, "total_age": 0, "count": 0}
     
-    demographics = {"male": 0, "female": 0, "avg_age": 0}
-    for result in results:
-        demographics[result['gender'].lower()] += 1
-        demographics['avg_age'] += result['age']
+    for image_path in glob(f"{image_folder}/*.jpg"):
+        result = classifier(image_path)
+        demographics[result[0]['gender'].lower()] += 1
+        demographics['total_age'] += result[0]['age']
+        demographics['count'] += 1
+    
+    demographics['avg_age'] = demographics['total_age'] / demographics['count']
+    demographics['male_percent'] = demographics['male'] / demographics['count'] * 100
+    demographics['female_percent'] = demographics['female'] / demographics['count'] * 100
     
-    demographics['avg_age'] /= len(results)
     return demographics
+
+stats = analyze_audience("customer_photos/")
+print(f"Average age: {stats['avg_age']:.1f}")
+print(f"Gender split: {stats['male_percent']:.1f}% Male, {stats['female_percent']:.1f}% Female")
 ```
 
-### Real-time Webcam
+### Age Verification
 ```python
-import cv2
 from transformers import pipeline
 
-classifier = pipeline("age-gender-classification", model="abhilash88/age-gender-prediction")
-cap = cv2.VideoCapture(0)
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
 
-while True:
-    ret, frame = cap.read()
-    if ret:
-        # Convert BGR to RGB
-        rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
-        result = classifier(rgb_frame)
-        
-        # Display prediction
-        text = f"Age: {result['age']}, Gender: {result['gender']}"
-        cv2.putText(frame, text, (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
-        cv2.imshow('Age-Gender Detection', frame)
-        
-    if cv2.waitKey(1) & 0xFF == ord('q'):
-        break
+def verify_age(image_path, min_age=18):
+    result = classifier(image_path)
+    age = result[0]['age']
+    confidence = result[0]['gender_confidence']
+    
+    if confidence < 0.7:  # Low confidence
+        return "Please provide a clearer image"
+    
+    if age >= min_age:
+        return f"Verified: {age} years old (meets {min_age}+ requirement)"
+    else:
+        return f"Age verification failed: {age} years old"
 
-cap.release()
-cv2.destroyAllWindows()
+verification = verify_age("id_photo.jpg", min_age=21)
+print(verification)
 ```
 
-## 🚀 Installation & Requirements
+## 🔧 Technical Details
 
-```bash
-# Minimal installation
-pip install transformers torch pillow
+- **Base Model**: google/vit-base-patch16-224 (Vision Transformer)
+- **Input Resolution**: 224×224 RGB images  
+- **Architecture**: Dual-head design with age regression and gender classification
+- **Training Dataset**: UTKFace (23,687 images)
+- **Training**: 15 epochs, AdamW optimizer, 2e-5 learning rate
 
-# Full installation with optional dependencies
-pip install transformers torch torchvision pillow opencv-python matplotlib
+## 🌟 Key Features
 
-# For development
-pip install transformers torch pillow pytest black flake8
+- ✅ **True one-line usage** with transformers pipeline
+- ✅ **High accuracy** (94.3% gender, 4.5 years age MAE)
+- ✅ **Multiple input types** (file paths, URLs, PIL Images, NumPy arrays)
+- ✅ **Batch processing** support
+- ✅ **Real-time capable** (~50ms inference)
+- ✅ **Google Colab ready**
+- ✅ **Production tested**
+
+## 🚀 Quick Start Examples
+
+### Absolute Minimal Usage
+```python
+from transformers import pipeline
+result = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)("image.jpg")
+print(f"Age: {result[0]['age']}, Gender: {result[0]['gender']}")
 ```
 
-**System Requirements:**
-- Python 3.7+
-- PyTorch 1.9+
-- Transformers 4.20+
-- 2GB RAM minimum (4GB recommended)
-- ~500MB disk space for model
+### With Helper Function
+```python
+from model import simple_predict
+print(simple_predict("image.jpg"))  # "25 years, Female (87% confidence)"
+```
 
-## ⚠️ Usage Guidelines
+### Error Handling
+```python
+from transformers import pipeline
 
-### ✅ Optimal Use Cases
-- **Adult demographic analysis** (16-60 years) - Best performance
-- **Social media content filtering** - High accuracy
-- **Marketing audience analysis** - Reliable demographics
-- **Age verification systems** - Good for adult detection
+classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
 
-### ⚠️ Limitations
-- **Children (0-12)**: Reduced accuracy due to limited training data
-- **Very elderly (70+)**: Higher variance in predictions
-- **Poor image quality**: Requires clear, well-lit faces
-- **Extreme angles**: Works best with frontal or near-frontal faces
+def safe_predict(image_path):
+    try:
+        result = classifier(image_path)
+        return f"Age: {result[0]['age']}, Gender: {result[0]['gender']}"
+    except Exception as e:
+        return f"Prediction failed: {e}"
 
-### 🎯 Best Practices
-- Use **pipeline approach** for ease of use
-- Ensure **good lighting** and **clear faces**
-- Consider **confidence thresholds** for your application
-- **Validate results** for edge cases in your domain
-- Use **batch processing** for multiple images
+prediction = safe_predict("any_image.jpg")
+print(prediction)
+```
 
-## 📄 Citation
+## 📝 Citation
 
 ```bibtex
 @misc{age-gender-prediction-2025,
@@ -343,17 +395,21 @@ pip install transformers torch pillow pytest black flake8
   year={2025},
   publisher={Hugging Face},
   url={https://huggingface.co/abhilash88/age-gender-prediction},
-  note={Pipeline-enabled model for easy integration}
+  note={One-liner pipeline with 94.3\% gender accuracy}
 }
 ```
 
-## 🔗 Related Links
+## 📄 License
 
-- **Model Card**: [abhilash88/age-gender-prediction](https://huggingface.co/abhilash88/age-gender-prediction)
-- **Transformers Documentation**: [Pipeline Tutorial](https://huggingface.co/docs/transformers/pipeline_tutorial)
-- **Vision Transformer**: [google/vit-base-patch16-224](https://huggingface.co/google/vit-base-patch16-224)
-- **Dataset**: [UTKFace Dataset](https://susanqq.github.io/UTKFace/)
+Licensed under Apache 2.0. Commercial use permitted with attribution.
 
 ---
 
-**🎉 New Feature**: Native Hugging Face Pipeline support makes this model incredibly easy to use! Try the one-liner examples above.
+**🎉 Ready to use!** Just one line of code to get accurate age and gender predictions from any facial image! 🚀
+
+**Try it now:**
+```python
+from transformers import pipeline
+result = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)("your_image.jpg")
+print(f"Age: {result[0]['age']}, Gender: {result[0]['gender']}")
+```