Create README.md

README.md

@@ -0,0 +1,276 @@
+---
+tags:
+- swahili
+- classification
+- multilabel
+- roberta
+- transformers
+- onnx
+- africa
+- nlp
+license: apache-2.0
+language:
+- sw
+- swa
+datasets:
+- custom
+metrics:
+- f1_score
+- precision
+- recall
+- hamming_loss
+pipeline_tag: text-classification
+task_categories:
+- text-classification
+task_ids:
+- multi-label-classification
+base_model:
+- benjamin/roberta-base-wechsel-swahili
+library_name: transformers
+---
+
+# Swahili Topic Classifier - Multi-label Classification
+
+## Model Details
+
+### Model Description
+A multi-label text classification model fine-tuned on RoBERTa-base Wechsel Swahili for classifying Swahili text into 8 predefined topics. The model can identify multiple applicable topics for a given text, providing confidence scores for each topic.
+
+- **Developed by**: NeboTech
+- **Model type**: Transformer-based (RoBERTa)
+- **Language(s)**: Swahili (Kiswahili)
+- **License**: Apache 2.0
+- **Finetuned from**: [RoBERTa-base Wechsel Swahili](https://huggingface.co/roberta-base-wechsel-swahili)
+- **Model version**: v2.0 (Multi-label Classification)
+
+### Model Architecture
+- **Base Model**: RoBERTa-base Wechsel Swahili
+- **Task**: Multi-label Sequence Classification
+- **Problem Type**: `multi_label_classification`
+- **Number of Labels**: 8
+- **Activation Function**: Sigmoid (for multi-label)
+- **Loss Function**: BCEWithLogitsLoss
+- **Output Format**: Binary vectors [batch_size, num_labels]
+
+### Model Variants
+- **v2.0** (Current): Multi-label classification - Returns multiple topics with confidence scores
+- **v1.0** (Legacy): Single-label classification - Returns single topic (available at `revision="v1.0-single-label"`)
+
+## Intended Use
+
+### Primary Use Cases
+- **Content Classification**: Categorize Swahili text messages, reports, or documents
+- **Case Management**: Automatically tag and route cases to appropriate departments
+- **Content Moderation**: Identify topics requiring attention (e.g., health emergencies, violence)
+- **Data Analytics**: Analyze trends and patterns in Swahili text data
+- **Information Routing**: Direct messages to relevant stakeholders based on topics
+
+### Out-of-Scope Uses
+- **Not suitable for**: Languages other than Swahili
+- **Not suitable for**: Very short text (< 5 words) or very long text (> 512 tokens)
+- **Not suitable for**: Real-time critical decision making without human oversight
+- **Not suitable for**: Medical diagnosis or legal advice
+
+## Training Details
+
+### Training Data
+- **Dataset**: Custom Swahili text dataset
+- **Language**: Swahili (Kiswahili)
+- **Data Collection**: U-Report platform messages and related Swahili text
+- **Preprocessing**: Text cleaning, normalization, and tokenization
+- **Data Balance**: Dataset balanced across 8 topics
+
+### Training Procedure
+- **Training Type**: Fine-tuning from pre-trained RoBERTa-base Wechsel Swahili
+- **Optimizer**: AdamW
+- **Learning Rate**: 2e-5
+- **Batch Size**: Variable (with gradient accumulation)
+- **Epochs**: 3
+- **Gradient Accumulation**: 4 steps
+- **Weight Decay**: 0.01
+- **Mixed Precision**: Enabled (FP16)
+- **Early Stopping**: Enabled (patience=2)
+
+### Training Hyperparametersl
+learning_rate: 2e-5
+per_device_train_batch_size: 4
+gradient_accumulation_steps: 4
+num_train_epochs: 3
+weight_decay: 0.01
+warmup_steps: 0
+max_grad_norm: 1.0
+fp16: true## Evaluation
+
+### Testing Data, Factors & Metrics
+- **Evaluation Dataset**: Held-out test set from balanced dataset
+- **Evaluation Metrics**:
+  - **F1 Score (Micro)**: Aggregated across all labels
+  - **F1 Score (Macro)**: Average per-label F1
+  - **F1 Score (Samples)**: Average per-sample F1
+  - **Precision (Micro/Macro)**: Classification precision
+  - **Recall (Micro/Macro)**: Classification recall
+  - **Hamming Loss**: Fraction of incorrectly predicted labels
+  - **Subset Accuracy**: Exact match accuracy
+
+### Results
+| Metric | Score |
+|--------|-------|
+| F1 Score (Micro) | 0.96 |
+| F1 Score (Macro) |0.96 |
+| F1 Score (Samples) |0.96 |
+| Precision (Micro) | 0.96 |
+| Recall (Micro) | 0.96 |
+| Hamming Loss | 0.009054 |
+| Subset Accuracy | 0.962 |
+
+## Model Performance Characteristics
+
+### Strengths
+- **Multi-label Capability**: Can identify multiple topics in a single text
+- **Confidence Scores**: Provides probability scores for each topic
+- **Swahili Language Support**: Specifically fine-tuned for Swahili text
+- **Efficient Inference**: ONNX format available for fast CPU inference
+- **Balanced Performance**: Trained on balanced dataset across all topics
+
+### Limitations
+- **Language Specific**: Only works with Swahili text
+- **Topic Coverage**: Limited to 8 predefined topics
+- **Context Dependency**: Performance may vary with text length and context
+- **Dialect Variations**: May not handle all Swahili dialects equally well
+- **Threshold Sensitivity**: Requires careful threshold tuning for optimal performance
+
+### Known Biases
+- **Training Data Bias**: Model reflects biases present in training data
+- **Geographic Bias**: May perform better on texts from regions in training data
+- **Topic Imbalance**: Some topics may have better representation in training data
+- **Cultural Context**: May not capture all cultural nuances in Swahili communication
+
+## How to Get Started with the Model
+
+### Using Transformers (PyTorch)
+
+from transformers import AutoModelForSequenceClassification, AutoTokenizer
+import torch
+
+# Load model
+model = AutoModelForSequenceClassification.from_pretrained(
+    "NeboTech/swahili-text-classifier",
+    problem_type="multi_label_classification"  # CRITICAL for multi-label
+)
+tokenizer = AutoTokenizer.from_pretrained("NeboTech/swahili-text-classifier")
+
+# Prepare input
+text = "Nataka kujua dalili za COVID-19 na jinsi ya kujilinda"
+inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True, max_length=256)
+
+# Get predictions
+model.eval()
+with torch.no_grad():
+    outputs = model(**inputs)
+    logits = outputs.logits  # Shape: [1, 8]
+
+# Apply sigmoid for multi-label
+probs = torch.sigmoid(logits)
+
+# Apply threshold
+threshold = 0.5
+predictions = (probs > threshold).float()
+
+# Get applicable topics
+applicable_topics = torch.where(predictions[0] == 1)[0].tolist()
+print(f"Applicable topics: {applicable_topics}")
+print(f"Probabilities: {probs[0].tolist()}")### Using ONNX Runtime
+
+import onnxruntime as ort
+import numpy as np
+from transformers import AutoTokenizer
+
+# Load tokenizer
+tokenizer = AutoTokenizer.from_pretrained("NeboTech/swahili-text-classifier")
+
+# Load ONNX model
+session = ort.InferenceSession("swahili_classifier.onnx")
+
+# Prepare input
+text = "Nataka kujua dalili za COVID-19"
+inputs = tokenizer(text, return_tensors="np", padding="max_length", truncation=True, max_length=256)
+
+# Run inference
+outputs = session.run(
+    None,
+    {
+        "input_ids": inputs["input_ids"].astype(np.int64),
+        "attention_mask": inputs["attention_mask"].astype(np.int64)
+    }
+)
+
+logits = outputs[0]  # Shape: [1, 8]
+
+# Apply sigmoid
+probs = 1 / (1 + np.exp(-logits))
+
+# Apply threshold
+threshold = 0.5
+predictions = (probs > threshold).astype(float)
+
+# Get topics
+applicable_topics = np.where(predictions[0] == 1)[0]
+print(f"Applicable topics: {applicable_topics}")## Topics (Label Mapping)
+
+| ID | Topic | Description |
+|----|-------|-------------|
+| 0 | COVID | COVID-19 related topics, symptoms, prevention |
+| 1 | EDUCATION | Educational content, school-related topics |
+| 2 | HEALTH | General health topics, medical information |
+| 3 | HIV/AIDS | HIV/AIDS related information and support |
+| 4 | MENSTRUAL HYGIENE | Menstrual health and hygiene topics |
+| 5 | NUTRITION | Nutrition, food, and dietary information |
+| 6 | U-REPORT | U-Report platform related content |
+| 7 | VIOLENCE AGAINST CHILDREN | Child protection and violence prevention |
+
+## Ethical Considerations
+
+### Ethical Use
+- **Human Oversight**: Always include human review for critical decisions
+- **Privacy**: Respect user privacy when processing text data
+- **Transparency**: Inform users when automated classification is used
+- **Fairness**: Monitor for biased outcomes across different user groups
+
+### Potential Risks
+- **Misclassification**: Incorrect topic assignment could misroute important messages
+- **False Positives/Negatives**: May miss urgent cases or flag non-urgent content
+- **Privacy Concerns**: Processing sensitive health and personal information
+- **Cultural Sensitivity**: May not fully capture cultural context and nuances
+
+### Recommendations
+- **Regular Monitoring**: Continuously monitor model performance in production
+- **Human Review**: Implement human review for high-stakes classifications
+- **Feedback Loop**: Collect and incorporate user feedback for improvements
+- **Bias Auditing**: Regularly audit for biases and fairness issues
+- **Threshold Tuning**: Adjust thresholds based on use case requirements
+
+## Citation
+
+@misc{swahili-topic-classifier-multilabel,
+  title={Swahili Topic Classifier - Multi-label Classification},
+  author={NeboTech},
+  year={2024},
+  publisher={Hugging Face},
+  howpublished={\\url{https://huggingface.co/NeboTech/swahili-text-classifier}},
+  note={Version 2.0 - Multi-label Classification}
+}## Additional Information
+
+### Model Files
+- `config.json`: Model configuration
+- `pytorch_model.bin` or `model.safetensors`: Model weights
+- `tokenizer.json`: Tokenizer model
+- `tokenizer_config.json`: Tokenizer configuration
+- `vocab.json`, `merges.txt`: Vocabulary files
+- `swahili_classifier.onnx`: ONNX model (separate repository)
+
+### Version History
+- **v2.0** (Current): Multi-label classification with sigmoid activation
+- **v1.0** (Legacy): Single-label classification with softmax activation
+
+### Contact
+For questions, issues, or contributions