Upload README.md with huggingface_hub

README.md

@@ -2,90 +2,75 @@
 language: ar
 tags:
 - text-classification
-- sentiment
+- sentiment-analysis
 - levantine
+- arabic
 - marbert
-- hate-speech
+- ordinal-classification
 metrics:
 - accuracy
-- f1
+- f1_macro
 model-index:
-- name: Levantine Toxic Classifier
+- name: Levantine Sentiment Classifier (Ordinal)
   results:
   - task:
       type: text-classification
-      name: Text Classification
+      name: Sentiment Analysis
     dataset:
       name: ArSenTD-LEV
       type: amitca71/marabert2-levantine-sentiment-model-dataset
     metrics:
     - type: accuracy
       value: 79.50%
-    - type: f1
-      value: 0.76
+    - type: f1_macro
+      value: 0.7635
 ---
 
-# 🛡️ Levantine Hate Speech Classifier (v2)
+# 🎭 Levantine Arabic Sentiment Classifier (Ordinal MARBERTv2)
 
-This model is a fine-tuned version of **MARBERTv2**, designed to detect **Hate Speech** and **Abusive Language** in Levantine Arabic tweets.
+This model is a fine-tuned version of **MARBERTv2**, designed to predict the sentiment of Levantine Arabic tweets (Jordanian, Lebanese, Palestinian, Syrian). 
 
-It is specifically trained to handle **Sarcasm** and **Indirect Threats** (e.g., "The grave is waiting" - القبر ناطر) which are often missed by standard models.
+**Technical Highlight:** This model was trained using an **Ordinal Loss Function** (Mean Squared Error combined with Cross-Entropy). This makes the model "distance-aware," meaning it heavily penalizes extreme mistakes (like confusing a highly positive tweet for a highly negative one). This makes its predictions far more reliable in edge cases!
 
 ## 📊 Performance
 | Metric | Score | Description |
 | :--- | :--- | :--- |
 | **Accuracy** | **79.50%** | Overall correctness on the test set. |
-| **F1 (Toxic)** | **0.76** | Ability to catch toxic tweets without false alarms. |
+| **F1 (Macro)** | **0.7635** | The balanced F1 score across all 3 classes. |
 
 ## 📖 Labels
 | ID | Label | Meaning |
 | :--- | :--- | :--- |
-| **0** | **Normal** | Safe, standard conversation (including non-hateful insults). |
-| **1** | **Toxic** | Hate speech, violence, or identity-based attacks. |
+| **0** | **Negative 😠** | Anger, complaints, sadness, or frustration. |
+| **1** | **Neutral 😐** | Objective facts, mixed emotions, or ambiguous statements. |
+| **2** | **Positive 😃** | Joy, praise, excitement, or satisfaction. |
 
 ## 🚀 How to Use (Python)
 
-This model includes a **custom threshold** optimization. For best results, use the code below to load the threshold automatically from the config.
+Because this is a standard 3-class model, you can easily load it using Hugging Face's built-in `pipeline`.
 
 
 ```python
-from transformers import pipeline, AutoConfig
-
-# 1. Load Model & Config
-model_id = "amitca71/marabert2-levantine-toxic-model"
-config = AutoConfig.from_pretrained(model_id)
-
-# 2. Get the Optimized Threshold (or default to 0.5)
-THRESHOLD = getattr(config, "custom_threshold", 0.5)
-print(f"⚙️ Using Threshold: {THRESHOLD}")
-
-# 3. Load Pipeline
-classifier = pipeline("text-classification", model=model_id, top_k=None)
-
-def predict(text):
-    # Get all scores (Normal + Toxic)
-    output = classifier(text)
-
-    # Handle list-of-lists vs list-of-dicts format
-    scores = output[0] if isinstance(output[0], list) else output
-
-    # Find the Toxic Score safely
-    toxic_score = 0.0
-    for item in scores:
-        if item['label'].lower() in ['toxic', 'label_1', '1']:
-            toxic_score = item['score']
-            break
-
-    # Apply Threshold
-    label = "TOXIC ⚠️" if toxic_score > THRESHOLD else "Normal ✅"
-
-    return {"text": text, "label": label, "score": round(toxic_score, 4)}
-
-# 4. Test
-print(predict("يا زلمة حل عني يا غبي"))  # Likely Normal (Insult)
-print(predict("القبر ناطر"))             # Likely Toxic (Threat)
+from transformers import pipeline
+
+# 1. Load Pipeline
+model_id = "amitca71/marabert2-levantine-sentiment"
+classifier = pipeline("text-classification", model=model_id, top_k=1)
+
+def predict_sentiment(text):
+    # Get the top prediction
+    result = classifier(text)[0]
+    
+    # Format the output cleanly
+    return {"text": text, "label": result['label'], "confidence": round(result['score'], 4)}
+
+# 2. Test Examples
+print(predict_sentiment("الجو اليوم بيعقد! طالعين مشوار"))            # Should be Positive
+print(predict_sentiment("والله طقت روحي من هالزحمة، شي بيقرف"))        # Should be Negative
+print(predict_sentiment("وصلت عالبيت من شوي."))                       # Should be Neutral
 ```
 
 ## ⚠️ Limitations
-* **Dialect:** Optimized for Levantine (Jordan, Lebanon, Palestine, Syria). May underperform on Egyptian or Gulf dialects.
-* **Context:** Very short tweets (<3 words) may lack sufficient context for accurate sarcasm detection.
+* **Dialect Focus:** Optimized heavily for Levantine Twitter. It may underperform or misunderstand idioms in Egyptian, Gulf, or Maghrebi dialects.
+* **The "Neutral" Bottleneck:** Like most sentiment models, detecting true "Neutral" text is the most challenging, as human annotators often mix objective facts with subtle sarcasm in this category.
+* **Arabizi:** While MARBERTv2 has some exposure to Arabizi (Arabic written in English/Latin letters), this model performs best on native Arabic script.