Update README.md

README.md

@@ -1,30 +1,296 @@
-# SENTRIX // Neural Sentiment Engine
-
-**SENTRIX** is a high-performance, mobile-first sentiment analysis dashboard. It utilizes a distributed hybrid architecture, combining a globally accessible Progressive Web App (PWA) with a dynamically hardware-accelerated local inference node.
-
-![Status](https://img.shields.io/badge/Status-Active-brightgreen)
-![Frontend](https://img.shields.io/badge/Frontend-GitHub_Pages-blue)
-![Backend](https://img.shields.io/badge/Backend-Flask-orange)
-![Model](https://img.shields.io/badge/Model-Hugging_Face-yellow)
-
-## 🏗️ System Architecture
-
-SENTRIX operates across three decoupled layers. The model weights are hosted in the cloud, the UI is served globally, and the mathematical inference runs locally on the host machine.
-
-```text
-[ Layer 1: Storage ]       [ Layer 2: Frontend ]       [ Layer 3: Backend ]
-  Hugging Face Hub             GitHub Pages               Local Host (PC/Mac)
-  (Model Weights)              (Web Interface)            (Flask Inference Node)
-        │                             │                             │
-        │ 1. Downloads weights        │ 3. Sends POST /analyze      │
-        │    on first startup         │    via local network IP     │
-        ▼                             ▼                             │
-  ┌────────────┐               ┌────────────┐               ┌───────▼──────┐
-  │ prem79/    │               │ sentrix_   │               │ app.py       │
-  │ sentrix_   ├──────────────►│ ML_IA      ├──────────────►│ (RoBERTa V2) │
-  │ roberta_V2 │               │ (UI)       │               │              │
-  └────────────┘               └────────────┘               └──────────────┘
-                                                                    │
-                                                                    │ 2. Caches model
-                                                                    │    in memory
-                                                                    ▼
+---
+language:
+- en
+- fr
+- es
+- de
+- pt
+license: mit
+tags:
+- sentiment-analysis
+- text-classification
+- roberta
+- twitter
+- nlp
+- fine-tuned
+datasets:
+- tweet_eval
+metrics:
+- accuracy
+- f1
+model-index:
+- name: sentrix_roberta_V2
+  results:
+  - task:
+      type: text-classification
+      name: Sentiment Analysis
+    metrics:
+    - type: accuracy
+      value: 0.8821
+    - type: f1
+      value: 0.8821
+---
+
+# sentrix_roberta_V2
+
+A fine-tuned RoBERTa model for binary sentiment classification on social media text. Trained on a balanced Twitter sentiment dataset with 88.2% accuracy on a held-out test set of 40,000 samples.
+
+---
+
+## Model Summary
+
+| Property | Value |
+|---|---|
+| Base model | `cardiffnlp/twitter-roberta-base-sentiment-latest` |
+| Architecture | RoBERTa-base |
+| Task | Binary Sentiment Classification |
+| Labels | `NEGATIVE` (0), `POSITIVE` (1) |
+| Test Accuracy | **88.21%** |
+| Test F1 | **88.21%** |
+| Training samples | ~80,000 |
+| Test samples | 40,000 (balanced) |
+| Max sequence length | 128 tokens |
+| Framework | PyTorch + HuggingFace Transformers |
+
+---
+
+## Intended Use
+
+This model is designed to classify the sentiment of short-form social media text — primarily tweets and product reviews — as either positive or negative.
+
+**Suitable for:**
+- Customer review sentiment classification
+- Social media monitoring
+- Product feedback analysis
+- Multilingual sentiment detection (EN, FR, ES, DE, PT)
+
+**Not suitable for:**
+- Long-form documents (truncated at 128 tokens)
+- Fine-grained emotion classification (joy, anger, fear, etc.)
+- Neutral/mixed sentiment detection (binary output only)
+
+---
+
+## Training Details
+
+### Base Model
+
+Fine-tuned from `cardiffnlp/twitter-roberta-base-sentiment-latest`, which was itself pre-trained on 58M tweets. This domain-specific pretraining gives the model strong priors for informal language, slang, abbreviations, and emoji context.
+
+### Dataset
+
+A balanced Twitter sentiment dataset sourced from Kaggle, split as follows:
+
+| Split | Samples | NEGATIVE | POSITIVE |
+|---|---|---|---|
+| Train | ~80,000 | 50% | 50% |
+| Validation | 20,000 | 50% | 50% |
+| Test | 40,000 | 20,000 | 20,000 |
+
+### Preprocessing
+
+Standard RoBERTa tweet preprocessing was applied:
+
+- URLs replaced with the token `http`
+- User mentions replaced with the token `@user`
+- Text truncated to 128 tokens maximum
+
+### Hyperparameters
+
+| Parameter | Value |
+|---|---|
+| Optimizer | AdamW |
+| Learning rate | Default Trainer schedule |
+| Batch size | Default HuggingFace Trainer |
+| Max epochs | 10 |
+| Early stopping | Best checkpoint saved on validation loss |
+| Evaluation strategy | Per 500 steps |
+| Metric for best model | Accuracy + F1 |
+| Training platform | Kaggle (GPU) |
+
+### Training Progress
+
+The model was evaluated every 500 steps. Training loss and validation loss both decreased consistently across the first three epochs:
+
+| Step | Train Loss | Val Loss | Accuracy | F1 |
+|---|---|---|---|---|
+| 500 | 0.8806 | 0.8685 | 85.00% | 85.00% |
+| 1000 | 0.8451 | 0.8348 | 86.25% | 86.25% |
+| 2000 | 0.8291 | 0.8075 | 86.84% | 86.83% |
+| 3000 | 0.7788 | 0.7987 | 87.32% | 87.31% |
+| 4000 | 0.7754 | 0.8005 | 87.53% | 87.53% |
+| 5000 | 0.7676 | 0.8098 | 87.59% | 87.58% |
+| 6000 | 0.7356 | 0.7944 | 87.72% | 87.72% |
+| 7000 | 0.7310 | 0.7979 | 87.68% | 87.68% |
+| 8000 | 0.6885 | 0.8235 | 87.74% | 87.74% |
+| 8500 | 0.6905 | 0.8104 | 87.72% | 87.72% |
+
+The best checkpoint was saved and used for final evaluation.
+
+---
+
+## Evaluation Results
+
+Evaluated on the held-out test set of 40,000 samples (20,000 per class).
+
+### Test Set Metrics
+
+| Metric | Value |
+|---|---|
+| Accuracy | **0.8821** |
+| F1 (macro) | **0.8821** |
+| Eval loss | 0.8102 |
+| Samples/second | 287.63 |
+
+### Classification Report
+
+```
+              precision    recall  f1-score   support
+
+    Negative       0.88      0.88      0.88     20,000
+    Positive       0.88      0.88      0.88     20,000
+
+    accuracy                           0.88     40,000
+   macro avg       0.88      0.88      0.88     40,000
+weighted avg       0.88      0.88      0.88     40,000
+```
+
+The model achieves symmetric performance across both classes, indicating no label bias from the balanced training set.
+
+---
+
+## Usage
+
+### Direct Inference with Pipeline
+
+```python
+from transformers import pipeline
+
+classifier = pipeline(
+    "text-classification",
+    model="prem79/sentrix_roberta_V2"
+)
+
+result = classifier("The camera quality on this phone is absolutely stunning")
+print(result)
+# [{'label': 'POSITIVE', 'score': 0.9505}]
+```
+
+### Manual Inference
+
+```python
+import torch
+from transformers import AutoTokenizer, AutoModelForSequenceClassification
+import torch.nn.functional as F
+
+model_id = "prem79/sentrix_roberta_V2"
+
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForSequenceClassification.from_pretrained(model_id)
+model.eval()
+
+def predict(text):
+    # Preprocess (standard RoBERTa tweet normalization)
+    import re
+    text = re.sub(r'http\S+', 'http', text)
+    text = re.sub(r'@\w+', '@user', text)
+
+    inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=128)
+    with torch.no_grad():
+        logits = model(**inputs).logits
+        probs = F.softmax(logits, dim=-1)[0]
+
+    labels = ["NEGATIVE", "POSITIVE"]
+    sentiment = labels[probs.argmax().item()]
+    return {
+        "sentiment": sentiment,
+        "negative": round(probs[0].item() * 100, 2),
+        "positive": round(probs[1].item() * 100, 2),
+    }
+
+# Examples
+print(predict("The new phone camera is absolutely stunning at night"))
+# {'sentiment': 'POSITIVE', 'negative': 4.95, 'positive': 95.05}
+
+print(predict("Battery is terrible, drains in 2 hours, not worth the price"))
+# {'sentiment': 'NEGATIVE', 'negative': 94.72, 'positive': 5.28}
+
+print(predict("Ce produit est incroyable! Très satisfait de la qualité."))
+# {'sentiment': 'POSITIVE', 'negative': 7.18, 'positive': 92.82}
+```
+
+### Batch Inference
+
+```python
+texts = [
+    "Absolutely love this product!",
+    "Worst experience I have ever had",
+    "This product is okay I guess, nothing special",
+]
+
+inputs = tokenizer(texts, padding=True, truncation=True, max_length=128, return_tensors="pt")
+with torch.no_grad():
+    logits = model(**inputs).logits
+    probs = F.softmax(logits, dim=-1)
+
+for text, prob in zip(texts, probs):
+    label = "POSITIVE" if prob[1] > prob[0] else "NEGATIVE"
+    print(f"{label} ({prob[1].item():.2%} pos) | {text}")
+```
+
+---
+
+## Live Demo
+
+This model powers the SENTRIX sentiment analysis web application:
+
+- Frontend: https://prem-479.github.io/sentrix_ML_IA/
+- Source: https://github.com/prem-479/sentrix_ML_IA
+
+The application demonstrates:
+- Real-time sentiment classification
+- Aspect extraction from product reviews
+- Multilingual input handling (EN, FR, ES, DE, PT)
+- Emoji signal detection
+- Confidence score visualization
+
+---
+
+## Limitations
+
+- **Binary only** — outputs NEGATIVE or POSITIVE only. Sarcasm and neutral/mixed sentiment are classified as one or the other based on dominant signal.
+- **Short text optimized** — trained on tweets (short text). Performance may degrade on long documents due to the 128-token truncation limit.
+- **Sarcasm** — the model does not detect sarcasm. "Oh great, another broken product" will likely be classified as POSITIVE.
+- **Multilingual** — the base model has some cross-lingual capability from Twitter pretraining, but was fine-tuned primarily on English data. Non-English accuracy is lower than English accuracy.
+- **Domain shift** — trained on Twitter/product review data. Performance on other domains (news, medical, legal) has not been evaluated.
+
+---
+
+## Citation
+
+If you use this model, please cite the base model:
+
+```bibtex
+@inproceedings{barbieri-etal-2020-tweeteval,
+    title = "{T}weet{E}val: Unified Benchmark and Comparative Evaluation for Tweet Classification",
+    author = "Barbieri, Francesco and Camacho-Collados, Jose and Espinosa Anke, Luis and Neves, Leonardo",
+    booktitle = "Findings of the Association for Computational Linguistics: EMNLP 2020",
+    year = "2020",
+    publisher = "Association for Computational Linguistics",
+}
+```
+
+---
+
+## Model Files
+
+| File | Description |
+|---|---|
+| `config.json` | Model architecture and label mapping |
+| `model.safetensors` | Model weights (499 MB) |
+| `tokenizer.json` | Tokenizer vocabulary |
+| `tokenizer_config.json` | Tokenizer configuration |
+
+---
+
+*Fine-tuned on Kaggle using GPU acceleration. Trained with HuggingFace Transformers and PyTorch.*