Upload README.md with huggingface_hub

README.md

@@ -1,137 +1,149 @@
----
-license: mit
-language:
-- en
-- fr
-- es
-- de
-- nl
-- it
-tags:
-- base_model:adapter:Qwen/Qwen2.5-1.5B
-- lora
-- transformers
-library_name: peft
-base_model: Qwen/Qwen2.5-1.5B
-pipeline_tag: text-classification
----
-
-# Uplifting Content Filter v5
+---
+license: mit
+language: en
+tags:
+- text-classification
+- content-filtering
+- multi-dimensional-scoring
+- knowledge-distillation
+library_name: transformers
+pipeline_tag: text-classification
+---
+
+# jeergrvgreg/uplifting-filter-v5
 
 ## Model Description
 
-A fine-tuned **Qwen2.5-1.5B** model with LoRA adapters for multi-dimensional uplifting content scoring.
+This model is a fine-tuned version of [Qwen/Qwen2.5-1.5B](https://huggingface.co/Qwen/Qwen2.5-1.5B)
+for multi-dimensional content scoring using the **uplifting** filter.
 
-This model evaluates news articles across **6 orthogonal dimensions** to identify genuinely uplifting content with documented positive outcomes - not just feel-good stories or speculation.
+The model was trained using **knowledge distillation** from Gemini Flash, learning to replicate
+its judgment patterns on content evaluation.
 
-**Key Innovation**: Uses an orthogonal dimension framework (inspired by LCSA methodology) to avoid the high correlation issues found in previous versions.
+**Filter Focus**: DOCUMENTED OUTCOMES for human/planetary wellbeing, not emotional tone or speculation
 
-## Dimensions
+## Intended Use
 
-The model scores articles on 6 dimensions:
+This model scores articles across 6 semantic dimensions:
 
-### Impact Domains (WHAT kind of uplift)
-| Dimension | Weight | Question |
-|-----------|--------|----------|
-| **Human Wellbeing Impact** | 25% | Health, safety, livelihoods improved? |
-| **Social Cohesion Impact** | 15% | Communities strengthened, solidarity built? |
-| **Justice & Rights Impact** | 10% | Wrongs addressed, rights expanded? |
+- **Human Wellbeing Impact** (weight: 0.25): Improvement in health, safety, livelihoods, or basic needs
+- **Social Cohesion Impact** (weight: 0.15): Communities strengthened, solidarity built, connections across groups
+- **Justice Rights Impact** (weight: 0.10): Wrongs addressed, accountability achieved, rights expanded
+- **Evidence Level** (weight: 0.20): How verified are the claimed outcomes?
+- **Benefit Distribution** (weight: 0.20): Who benefits? How accessible is the benefit?
+- **Change Durability** (weight: 0.10): How lasting is the change?
 
-### Assessment Dimensions (HOW real/accessible)
-| Dimension | Weight | Question |
-|-----------|--------|----------|
-| **Evidence Level** | 20% | Documented outcomes or speculation? |
-| **Benefit Distribution** | 20% | Who benefits? Elite → Universal? |
-| **Change Durability** | 10% | Temporary relief → Systemic change? |
+
+## Training Data
+
+- **Training samples**: 7,999
+- **Validation samples**: 1,000
+- **Oracle**: Gemini Flash (for ground truth generation)
+- **Quality threshold**: Articles with quality_score >= 0.7
+
+## Training Procedure
+
+### Model Architecture
+
+- **Base model**: Qwen/Qwen2.5-1.5B
+- **Parameters**: 1,562,197,504
+- **Task**: Multi-dimensional regression (8 outputs)
+- **Input**: Article title + content (max 512 tokens)
+- **Output**: 8 continuous scores (0-10 range)
+
+### Training Configuration
+
+- **Epochs**: 3
+- **Batch size**: 8
+- **Learning rate**: 2e-05
+- **Optimizer**: AdamW
+- **Loss function**: Mean Squared Error (MSE)
+- **Gradient checkpointing**: Enabled
 
 ## Performance
 
+### Overall Metrics
+
 | Metric | Value |
 |--------|-------|
-| **Validation MAE** | **0.681** |
-| Training MAE | 0.637 |
-| Validation RMSE | 0.880 |
+| Validation MAE | 0.6807 |
+| Training MAE | 0.6368 |
+| Validation RMSE | 0.8799 |
+| Training RMSE | 0.8215 |
+
+### Per-Dimension Performance (Validation MAE)
 
-### Per-Dimension MAE (Validation)
 | Dimension | MAE |
 |-----------|-----|
-| Human Wellbeing Impact | 0.686 |
-| Social Cohesion Impact | 0.704 |
-| Justice Rights Impact | 0.619 |
-| Evidence Level | 0.636 |
-| Benefit Distribution | 0.792 |
-| Change Durability | 0.648 |
-
-## Training Details
-
-- **Base Model**: Qwen/Qwen2.5-1.5B
-- **Training Mode**: Knowledge Distillation (from Gemini Flash oracle)
-- **Adapter**: LoRA (18.5M trainable params, 1.2% of model)
-- **Training Samples**: 7,999
-- **Validation Samples**: 1,000
-- **Epochs**: 3
-- **Batch Size**: 8
-- **Learning Rate**: 2e-5
-- **Max Length**: 512 tokens
+| Human Wellbeing Impact | 0.6857 |
+| Social Cohesion Impact | 0.7040 |
+| Justice Rights Impact | 0.6188 |
+| Evidence Level | 0.6363 |
+| Benefit Distribution | 0.7922 |
+| Change Durability | 0.6475 |
+
 
 ## Usage
 
 ```python
 from transformers import AutoTokenizer, AutoModelForSequenceClassification
-from peft import PeftModel
 import torch
 
-# Load base model and LoRA adapter
-base_model = AutoModelForSequenceClassification.from_pretrained(
-    "Qwen/Qwen2.5-1.5B",
-    num_labels=6,
-    problem_type="regression"
-)
-model = PeftModel.from_pretrained(base_model, "nexusmind/uplifting-filter-v5")
-tokenizer = AutoTokenizer.from_pretrained("nexusmind/uplifting-filter-v5")
+# Load model and tokenizer
+model_name = "jeergrvgreg/uplifting-filter-v5"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForSequenceClassification.from_pretrained(model_name)
 
-# Score an article
-article = "Title: Community garden feeds 500 families\n\nA new community garden..."
-inputs = tokenizer(article, return_tensors="pt", max_length=512, truncation=True)
+# Prepare input
+article = {
+    "title": "Example Article Title",
+    "content": "Article content here..."
+}
 
+text = f"{article['title']}\n\n{article['content']}"
+inputs = tokenizer(text, return_tensors="pt", max_length=512, truncation=True)
+
+# Get predictions
 with torch.no_grad():
     outputs = model(**inputs)
     scores = outputs.logits[0].numpy()
 
-dimensions = ["human_wellbeing_impact", "social_cohesion_impact", "justice_rights_impact",
-              "evidence_level", "benefit_distribution", "change_durability"]
+# Dimension names
+dimensions = ['human_wellbeing_impact', 'social_cohesion_impact', 'justice_rights_impact', 'evidence_level', 'benefit_distribution', 'change_durability']
 
+# Print scores
 for dim, score in zip(dimensions, scores):
-    print(f"{dim}: {score:.1f}")
+    print(f"{dim}: {score:.2f}")
 ```
 
-## Gatekeeper Rule
-
-**Evidence Level < 3 → Overall score capped at 3.0**
-
-Speculation without documented outcomes cannot be truly uplifting.
-
 ## Limitations
 
-- Trained on multilingual news articles (61% English, 31% French, 7% Spanish, <1% German/Dutch/Italian)
-- MAE of ~0.68 means predictions within ±0.7 of oracle on average
-- `benefit_distribution` dimension has highest error (0.79 MAE)
-- Model focuses on documented outcomes, not emotional tone
+- Model was trained on English news articles
+- Performance may vary on other content types
+- Validation MAE of 0.6807 indicates ~0.8 point average error on 0-10 scale
+- Some overfitting observed (train/val gap: 0.04)
 
-## License
+## Ethical Considerations
 
-MIT
+This model evaluates content based on specific semantic dimensions. Users should:
+- Understand the filter's focus and biases
+- Not use as sole decision-maker for content moderation
+- Regularly evaluate model performance on their specific use case
+- Be aware that automated scoring may miss nuance
 
 ## Citation
 
+If you use this model, please cite:
+
 ```bibtex
-@misc{uplifting_filter_v5,
-  title={Uplifting Content Filter v5},
-  author={NexusMind},
+@misc{uplifting_filter_v5.0,
+  title={Uplifting Content Filter},
+  author={Your Name},
   year={2025},
-  url={https://huggingface.co/nexusmind/uplifting-filter-v5}
+  url={https://huggingface.co/jeergrvgreg/uplifting-filter-v5}
 }
 ```
-### Framework versions
 
-- PEFT 0.17.1
+## Model Card Contact
+
+For questions or feedback about this model, please open an issue in the repository.