Update README.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -1,3 +1,410 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+library_name: scikit-learn
+tags:
+  - scikit-learn
+  - sklearn
+  - text-classification
+  - vietnamese
+  - nlp
+  - sonar
+  - tf-idf
+  - logistic-regression
+  - svc
+  - support-vector-classification
+datasets:
+  - vntc
+  - undertheseanlp/UTS2017_Bank
+metrics:
+  - accuracy
+  - precision
+  - recall
+  - f1-score
+model-index:
+  - name: sonar-core-1
+    results:
+      - task:
+          type: text-classification
+          name: Vietnamese News Classification
+        dataset:
+          name: VNTC
+          type: vntc
+        metrics:
+          - type: accuracy
+            value: 0.9280
+            name: Test Accuracy (SVC)
+          - type: precision
+            value: 0.92
+            name: Weighted Precision
+          - type: recall
+            value: 0.92
+            name: Weighted Recall
+          - type: f1-score
+            value: 0.92
+            name: Weighted F1-Score
+      - task:
+          type: text-classification
+          name: Vietnamese Banking Text Classification
+        dataset:
+          name: UTS2017_Bank
+          type: undertheseanlp/UTS2017_Bank
+        metrics:
+          - type: accuracy
+            value: 0.7247
+            name: Test Accuracy (SVC)
+          - type: precision
+            value: 0.65
+            name: Weighted Precision (SVC)
+          - type: recall
+            value: 0.72
+            name: Weighted Recall (SVC)
+          - type: f1-score
+            value: 0.66
+            name: Weighted F1-Score (SVC)
+language:
+  - vi
+pipeline_tag: text-classification
+---
+
+# Sonar Core 1 - Vietnamese Text Classification Model
+
+A machine learning-based text classification model designed for Vietnamese language processing. Built on TF-IDF feature extraction pipeline combined with Support Vector Classification (SVC) and Logistic Regression, achieving **92.80% accuracy** on VNTC (news) and **72.47% accuracy** on UTS2017_Bank (banking) datasets with SVC.
+
+📋 **[View Detailed System Card](https://huggingface.co/undertheseanlp/sonar_core_1/blob/main/Sonar%20Core%201%20-%20System%20Card.md)** for comprehensive model documentation, performance analysis, and limitations.
+
+## Model Description
+
+**Sonar Core 1** is a Vietnamese text classification model that supports multiple domains including news categorization and banking text classification. The model is specifically designed for Vietnamese news article classification, banking text categorization, content categorization for Vietnamese text, and document organization and tagging.
+
+### Model Architecture
+
+- **Algorithm**: TF-IDF + SVC/Logistic Regression Pipeline
+- **Feature Extraction**: CountVectorizer with 20,000 max features
+- **N-gram Support**: Unigram and bigram (1-2)
+- **TF-IDF**: Transformation with IDF weighting
+- **Classifier**: Support Vector Classification (SVC) / Logistic Regression with optimized parameters
+- **Framework**: scikit-learn ≥1.6
+- **Caching System**: Hash-based caching for efficient processing
+
+## Supported Datasets & Categories
+
+### VNTC Dataset - News Categories (10 classes)
+1. **chinh_tri_xa_hoi** - Politics and Society
+2. **doi_song** - Lifestyle
+3. **khoa_hoc** - Science
+4. **kinh_doanh** - Business
+5. **phap_luat** - Law
+6. **suc_khoe** - Health
+7. **the_gioi** - World News
+8. **the_thao** - Sports
+9. **van_hoa** - Culture
+10. **vi_tinh** - Information Technology
+
+### UTS2017_Bank Dataset - Banking Categories (14 classes)
+1. **ACCOUNT** - Account services
+2. **CARD** - Card services
+3. **CUSTOMER_SUPPORT** - Customer support
+4. **DISCOUNT** - Discount offers
+5. **INTEREST_RATE** - Interest rate information
+6. **INTERNET_BANKING** - Internet banking services
+7. **LOAN** - Loan services
+8. **MONEY_TRANSFER** - Money transfer services
+9. **OTHER** - Other services
+10. **PAYMENT** - Payment services
+11. **PROMOTION** - Promotional offers
+12. **SAVING** - Savings accounts
+13. **SECURITY** - Security features
+14. **TRADEMARK** - Trademark/branding
+
+## Installation
+
+```bash
+pip install scikit-learn>=1.6 joblib
+```
+
+## Usage
+
+### Training the Model
+
+#### VNTC Dataset (News Classification)
+```bash
+# Default training with VNTC dataset
+python train.py --dataset vntc --model logistic
+
+# With specific parameters
+python train.py --dataset vntc --model logistic --max-features 20000 --ngram-min 1 --ngram-max 2
+```
+
+#### UTS2017_Bank Dataset (Banking Text Classification)
+```bash
+# Train with UTS2017_Bank dataset (SVC recommended)
+python train.py --dataset uts2017 --model svc_linear
+
+# Train with Logistic Regression
+python train.py --dataset uts2017 --model logistic
+
+# With specific parameters (SVC)
+python train.py --dataset uts2017 --model svc_linear --max-features 20000 --ngram-min 1 --ngram-max 2
+
+# Compare multiple configurations
+python train.py --dataset uts2017 --compare
+```
+
+### Training from Scratch
+
+```python
+from train import train_notebook
+
+# Train VNTC model
+vntc_results = train_notebook(
+    dataset="vntc",
+    model_name="logistic",
+    max_features=20000,
+    ngram_min=1,
+    ngram_max=2
+)
+
+# Train UTS2017_Bank model
+bank_results = train_notebook(
+    dataset="uts2017",
+    model_name="logistic",
+    max_features=20000,
+    ngram_min=1,
+    ngram_max=2
+)
+```
+
+## Performance Metrics
+
+### VNTC Dataset Performance
+- **Training Accuracy**: 95.39%
+- **Test Accuracy (SVC)**: 92.80%
+- **Test Accuracy (Logistic Regression)**: 92.33%
+- **Training Samples**: 33,759
+- **Test Samples**: 50,373
+- **Training Time (SVC)**: ~54.6 minutes
+- **Training Time (Logistic Regression)**: ~31.40 seconds
+- **Best Performing**: Sports (98% F1-score)
+- **Challenging Category**: Lifestyle (76% F1-score)
+
+### UTS2017_Bank Dataset Performance
+- **Training Accuracy (SVC)**: 95.07%
+- **Test Accuracy (SVC)**: 72.47%
+- **Test Accuracy (Logistic Regression)**: 70.96%
+- **Training Samples**: 1,581
+- **Test Samples**: 396
+- **Training Time (SVC)**: ~5.3 seconds
+- **Training Time (Logistic Regression)**: ~0.78 seconds
+- **Best Performing**: TRADEMARK (89% F1-score with SVC), CUSTOMER_SUPPORT (77% F1-score with SVC)
+- **SVC Improvements**: LOAN (+0.50 F1), DISCOUNT (+0.22 F1), INTEREST_RATE (+0.18 F1)
+- **Challenges**: Many minority classes with insufficient training data
+
+## Using the Pre-trained Models
+
+### VNTC Model (Vietnamese News Classification)
+
+```python
+from huggingface_hub import hf_hub_download
+import joblib
+
+# Download and load VNTC model
+vntc_model = joblib.load(
+    hf_hub_download("undertheseanlp/sonar_core_1", "vntc_classifier_20250927_161550.joblib")
+)
+
+# Enhanced prediction function
+def predict_text(model, text):
+    probabilities = model.predict_proba([text])[0]
+
+    # Get top 3 predictions sorted by probability
+    top_indices = probabilities.argsort()[-3:][::-1]
+    top_predictions = []
+    for idx in top_indices:
+        category = model.classes_[idx]
+        prob = probabilities[idx]
+        top_predictions.append((category, prob))
+
+    # The prediction should be the top category
+    prediction = top_predictions[0][0]
+    confidence = top_predictions[0][1]
+
+    return prediction, confidence, top_predictions
+
+# Make prediction on news text
+news_text = "Đội tuyển bóng đá Việt Nam giành chiến thắng"
+prediction, confidence, top_predictions = predict_text(vntc_model, news_text)
+
+print(f"News category: {prediction}")
+print(f"Confidence: {confidence:.3f}")
+print("Top 3 predictions:")
+for i, (category, prob) in enumerate(top_predictions, 1):
+    print(f"  {i}. {category}: {prob:.3f}")
+```
+
+### UTS2017_Bank Model (Vietnamese Banking Text Classification)
+
+```python
+from huggingface_hub import hf_hub_download
+import joblib
+
+# Download and load UTS2017_Bank model (latest SVC model)
+bank_model = joblib.load(
+    hf_hub_download("undertheseanlp/sonar_core_1", "uts2017_bank_classifier_20250928_060819.joblib")
+)
+
+# Enhanced prediction function (same as above)
+def predict_text(model, text):
+    probabilities = model.predict_proba([text])[0]
+
+    # Get top 3 predictions sorted by probability
+    top_indices = probabilities.argsort()[-3:][::-1]
+    top_predictions = []
+    for idx in top_indices:
+        category = model.classes_[idx]
+        prob = probabilities[idx]
+        top_predictions.append((category, prob))
+
+    # The prediction should be the top category
+    prediction = top_predictions[0][0]
+    confidence = top_predictions[0][1]
+
+    return prediction, confidence, top_predictions
+
+# Make prediction on banking text
+bank_text = "Tôi muốn mở tài khoản tiết kiệm"
+prediction, confidence, top_predictions = predict_text(bank_model, bank_text)
+
+print(f"Banking category: {prediction}")
+print(f"Confidence: {confidence:.3f}")
+print("Top 3 predictions:")
+for i, (category, prob) in enumerate(top_predictions, 1):
+    print(f"  {i}. {category}: {prob:.3f}")
+```
+
+### Using Both Models
+
+```python
+from huggingface_hub import hf_hub_download
+import joblib
+
+# Load both models
+vntc_model = joblib.load(
+    hf_hub_download("undertheseanlp/sonar_core_1", "vntc_classifier_20250927_161550.joblib")
+)
+bank_model = joblib.load(
+    hf_hub_download("undertheseanlp/sonar_core_1", "uts2017_bank_classifier_20250928_060819.joblib")
+)
+
+# Enhanced prediction function for both models
+def predict_text(model, text):
+    probabilities = model.predict_proba([text])[0]
+
+    # Get top 3 predictions sorted by probability
+    top_indices = probabilities.argsort()[-3:][::-1]
+    top_predictions = []
+    for idx in top_indices:
+        category = model.classes_[idx]
+        prob = probabilities[idx]
+        top_predictions.append((category, prob))
+
+    # The prediction should be the top category
+    prediction = top_predictions[0][0]
+    confidence = top_predictions[0][1]
+
+    return prediction, confidence, top_predictions
+
+# Function to classify any Vietnamese text
+def classify_vietnamese_text(text, domain="auto"):
+    """
+    Classify Vietnamese text using appropriate model with detailed predictions
+
+    Args:
+        text: Vietnamese text to classify
+        domain: "news", "banking", or "auto" to detect domain
+
+    Returns:
+        tuple: (prediction, confidence, top_predictions, domain_used)
+    """
+    if domain == "news":
+        prediction, confidence, top_predictions = predict_text(vntc_model, text)
+        return prediction, confidence, top_predictions, "news"
+    elif domain == "banking":
+        prediction, confidence, top_predictions = predict_text(bank_model, text)
+        return prediction, confidence, top_predictions, "banking"
+    else:
+        # Try both models and return higher confidence
+        news_pred, news_conf, news_top = predict_text(vntc_model, text)
+        bank_pred, bank_conf, bank_top = predict_text(bank_model, text)
+
+        if news_conf > bank_conf:
+            return f"NEWS: {news_pred}", news_conf, news_top, "news"
+        else:
+            return f"BANKING: {bank_pred}", bank_conf, bank_top, "banking"
+
+# Examples
+examples = [
+    "Đội tuyển bóng đá Việt Nam thắng 2-0",
+    "Tôi muốn vay tiền mua nhà",
+    "Chính phủ thông qua luật mới"
+]
+
+for text in examples:
+    category, confidence, top_predictions, domain = classify_vietnamese_text(text)
+    print(f"Text: {text}")
+    print(f"Category: {category}")
+    print(f"Confidence: {confidence:.3f}")
+    print(f"Domain: {domain}")
+    print("Top 3 predictions:")
+    for i, (cat, prob) in enumerate(top_predictions, 1):
+        print(f"  {i}. {cat}: {prob:.3f}")
+    print()
+```
+
+## Model Parameters
+
+- `dataset`: Dataset to use ("vntc" or "uts2017")
+- `model`: Model type ("logistic" or "svc" - SVC recommended for best performance)
+- `max_features`: Maximum number of TF-IDF features (default: 20000)
+- `ngram_min/max`: N-gram range (default: 1-2)
+- `split_ratio`: Train/test split ratio for UTS2017 (default: 0.2)
+- `n_samples`: Optional sample limit for quick testing
+
+## Limitations
+
+1. **Language Specificity**: Only works with Vietnamese text
+2. **Domain Specificity**: Optimized for specific domains (news and banking)
+3. **Feature Limitations**: Limited to 20,000 most frequent features
+4. **Class Imbalance Sensitivity**: Performance degrades with imbalanced datasets
+5. **Specific Weaknesses**:
+   - VNTC: Lower performance on lifestyle category (71% recall)
+   - UTS2017_Bank: Poor performance on minority classes despite SVC improvements
+   - SVC requires longer training time compared to Logistic Regression
+
+## Ethical Considerations
+
+- Model reflects biases present in training datasets
+- Performance varies significantly across categories
+- Should be validated on target domain before deployment
+- Consider class imbalance when interpreting results
+
+## Additional Information
+
+- **Repository**: https://huggingface.co/undertheseanlp/sonar_core_1
+- **Framework Version**: scikit-learn ≥1.6
+- **Python Version**: 3.10+
+- **System Card**: See [Sonar Core 1 - System Card](https://huggingface.co/undertheseanlp/sonar_core_1/blob/main/Sonar%20Core%201%20-%20System%20Card.md) for detailed documentation
+
+## Citation
+
+If you use this model, please cite:
+
+```bibtex
+@misc{undertheseanlp_2025,
+    author       = { undertheseanlp },
+    title        = { Sonar Core 1 - Vietnamese Text Classification Model },
+    year         = 2025,
+    url          = { https://huggingface.co/undertheseanlp/sonar_core_1 },
+    doi          = { 10.57967/hf/6599 },
+    publisher    = { Hugging Face }
+}
+```