Create README.md

README.md

@@ -0,0 +1,147 @@
+---
+library_name: transformers
+tags: []
+---
+
+# Model Description
+
+ This model is based on Mistral 7B and has been fine-tuned for emotion recognition and empathetic conversational support within mental health contexts. It is derived from the research presented in the paper "The Emotional Spectrum of LLMs: Leveraging Empathy and Emotion-Based Markers for Mental Health Support". The model’s architecture and fine-tuning details follow the methodology outlined in that publication—specifically, leveraging next-token prediction for emotion labeling, progressive construction of a user emotional profile throughout conversation, and interpretable emotional embeddings for preliminary mental health screening.aclanthology+4​
+Reference
+For full details see:
+De Grandi, Ravenda et al. (2025). "The Emotional Spectrum of LLMs: Leveraging Empathy and Emotion-Based Markers for Mental Health Support." 
+
+ # Usage Example: Emotional Profile Extraction
+
+ Suppose you have a list of sentences and want to compute the aggregated emotional profile (distribution of emotions predicted over the set):
+
+ ## Example Python Code
+
+ ```{python}
+import torch
+import transformers
+from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+
+ model_name = 'DeGra/RACLETTE-v0.2'
+
+ bnb_config = BitsAndBytesConfig(
+    load_in_4bit=True,
+    bnb_4bit_quant_type="nf4",
+    bnb_4bit_compute_dtype=torch.float16,
+)
+
+ model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    quantization_config=bnb_config,
+    trust_remote_code=True
+)
+model.config.use_cache = False
+
+ tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
+tokenizer.pad_token = tokenizer.eos_token
+
+ generation_pipeline = transformers.pipeline(
+    "text-generation",
+    model=model,
+    tokenizer=tokenizer,
+    torch_dtype=torch.bfloat16,
+    trust_remote_code=True,
+    device_map="auto",
+)
+
+ def filter_limit_chars(text, limit_chars, max_limited_chars=2, stop_at_max=False):
+    count, index = 0, [0]
+    for separator in limit_chars:
+        separator_count = text.count(separator)
+        count += separator_count
+        i = 0
+        for _ in range(separator_count):
+            i = text.find(separator, i)
+            index.append(i if not stop_at_max else i+len(separator))
+            i += len(separator)
+    index.sort()
+    index.append(len(text))
+    if count >= max_limited_chars:
+        text = text[0:index[max_limited_chars+1] if not stop_at_max else index[max_limited_chars]]
+    return text
+
+ def predict_emotion(prompt, num_return_emotions=10):
+    sequences = generation_pipeline(
+        prompt,
+        min_new_tokens=2,
+        max_new_tokens=5,
+        do_sample=True,
+        top_k=5,
+        num_return_sequences=num_return_emotions,
+        eos_token_id=tokenizer.eos_token_id,
+    )
+    emotions_count = {}
+    for seq in sequences:
+        emotion = seq['generated_text'][len(prompt):].strip()
+        emotion = emotion.split('<|assistant|>',1)[0].split('<|endoftext|>',1)[0]
+        emotion = filter_limit_chars(emotion, ['|','<','>',',','.'], 0, False).strip()
+        emotions_count[emotion] = emotions_count.get(emotion, 0) + 1
+    return emotions_count
+
+ # Example: Extract emotional profile from sentences
+emotion_dict = {e: 0 for e in ["surprised","excited","angry","proud","sad","annoyed","grateful","lonely","afraid","terrified","guilty","impressed","disgusted","hopeful","confident","furious","anxious","anticipating","joyful","nostalgic","disappointed","prepared","jealous","content","devastated","embarrassed","caring","sentimental","trusting","ashamed","apprehensive","faithful"]}
+
+ sentences = ["I'm feeling really down lately.", "I don't know if I can handle this anymore.", "Today I got some good news!"]
+
+ for sent in sentences:
+    prompt = f'<|prompter|>{sent}<|endoftext|><|emotion|>'
+    emotions_count = predict_emotion(prompt)
+    for emotion, count in emotions_count.items():
+        if emotion in emotion_dict:
+            emotion_dict[emotion] += count
+
+ print(emotion_dict)
+```
+
+
+
+## Model Details
+
+### Model Description
+
+<!-- Provide a longer summary of what this model is. -->
+
+This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+
+- **Developed by:** DeGRa
+- **Model type:** Fine-Tuned Mistral-7B
+- **Language(s) (NLP):** English
+
+
+### Direct Use
+
+This model is primarily designed for use as an **empathetic chatbot** that understands and responds to users' emotional states in a conversational setting. It progressively builds an emotional profile of the user over multiple turns, enabling more personalized and compassionate interactions. The model leverages generative next-token prediction to infer emotions and produce empathetic responses in real-time, creating a natural and emotionally aware dialogue experience.
+
+### Downstream Use
+
+Beyond chatbot applications, this model can be utilized for **emotion classification** tasks. By extracting emotion embeddings from text inputs, it can serve as a foundational tool for emotion detection and analysis in various downstream applications such as sentiment analysis, mental health screening, social media monitoring, and other affective computing domains. Its interpretable emotional profiles enable explainable insights for psychological and clinical tasks.
+
+### Out-of-Scope Use
+
+This model is **not intended** for direct clinical diagnosis or as a standalone mental health intervention tool. It should not be used in applications requiring professional medical judgment. The model may not perform well in domains with language or emotional expressions significantly different from those encountered during fine-tuning. Additionally, it should not be deployed where accurate identification of serious mental health crises without human oversight is required.
+
+## Bias, Risks, and Limitations
+
+The model inherits biases from the **finetuning data**, which consists of publicly available Reddit posts and empathetic dialogue datasets that may contain demographic, cultural, or social biases. These biases can affect emotion recognition accuracy and response generation, potentially amplifying stereotypes or missing subtle emotional nuances in under-represented populations. Careful evaluation and continuous monitoring are necessary when deploying the model, especially in sensitive mental health contexts. Users should be informed of these limitations and encouraged to complement model outputs with expert human evaluation.
+
+
+
+
+## Citation 
+
+
+```
+@inproceedings{de2025emotional,
+  title={The emotional spectrum of llms: Leveraging empathy and emotion-based markers for mental health support},
+  author={De Grandi, Alessandro and Ravenda, Federico and Raballo, Andrea and Crestani, Fabio},
+  booktitle={Proceedings of the 10th Workshop on Computational Linguistics and Clinical Psychology (CLPsych 2025)},
+  pages={26--43},
+  year={2025}
+}
+```
+
+