Update README.md

README.md

@@ -3,200 +3,167 @@ base_model: unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit
 library_name: peft
 ---
 
-# Model Card for Model ID
 
-<!-- Provide a quick summary of what the model is/does. -->
+# Monolingual English Model Adapters for Neutral and Stance-Aware Definition Generation
 
+These models are trained to generate neutral (noslang, wordnet, oxford) and biased (slang, all), stance-aware definitions. 
 
+These adapters should be used together with the base model *unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit* and requires *unsloth* installation. 
 
-## Model Details
 
-### Model Description
+The models are instruction-tuned on the  dictionary data:
+WordNet (Ishiwatari et al., 2019), Oxford (Gadet-
+sky et al., 2018),  Wiktionary (Mickus
+et al., 2022), Urban Dic-
+tionary (Ni and Wang, 2017). 
 
-<!-- Provide a longer summary of what this model is. -->
 
+|   Model           | Training data          |
+|-------------------|--------------------------|
+| LT3/definitions-oxford-llama-8B-instruct        | Oxford                  |
+| LT3/definitions-all-noslang-llama-8B-instruct   | WordNet, Wiki, Oxford                  | 
+| LT3/definitions-all-llama-8B-instruct    | WordNet, Wiki, Oxford, Urban                  | 
+| LT3/definitions-wordnet-llama-8B-instruct   |WordNet                | 
+| LT3/definitions-slang-llama-8B-instruct    | Urban                 | 
 
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
 
-### Model Sources [optional]
 
-<!-- Provide the basic links for the model. -->
+## How to use
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+The models expect a usage example and a keyword as input:
 
-## Uses
+- keyword = "death penalty"
+- example usage (argument) = "As long as death penalty is kept, this confirms that our society is founded on violence."
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+While we tested the models on the argumentative data to test their potential to produce stance-aware definitions, they can be used for a general definition generation task for various contexts.
+If you want to generate neutral definitions, avoid using slang- and all- models, these models aim to capture contextual bias that reflects the attitude of the author (pro, contra) towards the keyword. 
 
-### Direct Use
+The following code can be used for the definition generation task:
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
 
-[More Information Needed]
+```python
+import torch
+from unsloth import FastLanguageModel
+from transformers import AutoTokenizer
 
-### Downstream Use [optional]
+# Load model + adapter
+BASE_MODEL = "unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit"
+#ADAPTER_PATH = "LT3/definitions-all-llama-8B-instruct"
+#ADAPTER_PATH = "LT3/definitions-slang-llama-8B-instruct"
+#ADAPTER_PATH = "LT3/definitions-oxford-llama-8B-instruct"
+#ADAPTER_PATH = "LT3/definitions-all-noslang-llama-8B-instruct"
+ADAPTER_PATH = "LT3/definitions-wordnet-llama-8B-instruct"
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+MAX_SEQ_LENGTH = 512
 
-[More Information Needed]
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name=BASE_MODEL,
+    max_seq_length=MAX_SEQ_LENGTH,
+    dtype="float16",  # or "bfloat16" if needed
+    load_in_4bit=True
+)
 
-### Out-of-Scope Use
+model.load_adapter(ADAPTER_PATH)
+FastLanguageModel.for_inference(model)
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+# Prompt variants
+PROMPTS = {
+    "definition_0": "What is the definition of {keyword} in the following text?",
+   # "definition_1": "What is the contextual definition of {keyword} in the following text?",
+   # "definition_2": "In what sense is the {keyword} used in the following text?",
+   # "definition_3": "What is the persuasive definition of {keyword} in the following text?",
+   # "definition_4": "What is the emotionally charged definition of {keyword} in the following text?"
+}
 
-[More Information Needed]
+# Alpaca-style prompt formatting
+def format_prompt(instruction, context):
+    return f"""Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.
 
-## Bias, Risks, and Limitations
+### Instruction:
+{instruction}
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+### Input:
+{context}
 
-[More Information Needed]
+### Response:
+"""
 
-### Recommendations
+# Clean model output
+def clean_response(response):
+    return response.split("### Response:")[-1].strip()
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+# Your example input
+keyword = "death penalty"
+argument = "As long as death penalty is kept, this confirms that our society is founded on violence."
 
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+# Generate for each prompt variant
+print(f"\n Argument:\n{argument}\n")
+for name, template in PROMPTS.items():
+    instruction = template.format(keyword=keyword)
+    prompt = format_prompt(instruction, argument)
 
-## How to Get Started with the Model
+    inputs = tokenizer([prompt], return_tensors="pt").to("cuda")
+    outputs = model.generate(
+        **inputs,
+        max_new_tokens=100,
+        do_sample=True,
+        temperature=0.7,
+        use_cache=True
+    )
 
-Use the code below to get started with the model.
+    decoded = tokenizer.decode(outputs[0], skip_special_tokens=True)
+    definition = clean_response(decoded)
 
-[More Information Needed]
+    print(f" {name}:\n{definition}\n")
 
-## Training Details
 
-### Training Data
+```
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
 
-[More Information Needed]
+## Model Performance
 
-### Training Procedure
+The best model for the general definition generation task is oxford-llama. The lower plausibility score for slang- and all- models means the definitions are biased. These models can be further used to explore the generation of 
+contextual definitions that capture stance-related bias (pro or contra the keyword). 
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
-
-## Evaluation
-
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
-**BibTeX:**
-
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
-
-## Model Card Authors [optional]
-
-[More Information Needed]
-
-## Model Card Contact
-
-[More Information Needed]
-### Framework versions
-
-- PEFT 0.13.2
+|   Model           | BERTScoreF1 [%]                |   Plausibility [%]  |
+|-------------------|--------------------------|--------------|
+| LT3/definitions-oxford-llama-8B-instruct        | 88.2                   | 84.5      |
+| LT3/definitions-all-noslang-llama-8B-instruct   | 86.0                   | 79.8       |
+| LT3/definitions-all-llama-8B-instruct    | 86.5                   | 53.25       |
+| LT3/definitions-wordnet-llama-8B-instruct   | 87.0                  | 43.00       |
+| LT3/definitions-slang-llama-8B-instruct    | 86.8                 | 37.25       |
+
+
+
+
+### BibTeX entry and citation info
+
+If you would like to use or cite our paper or model, feel free to use the following BibTeX code:
+
+```bibtex
+@inproceedings{evgrafova-etal-2025-stance,
+    title = "Stance-aware Definition Generation for Argumentative Texts",
+    author = "Evgrafova, Natalia  and
+      De Langhe, Loic
+and
+ Hoste, Veronique and
+      Lefever, Els  ",
+    editor = "Chistova, Elena  and
+      Cimiano, Philipp  and
+      Haddadan, Shohreh  and
+      Lapesa, Gabriella  and
+      Ruiz-Dolz, Ramon",
+    booktitle = "Proceedings of the 12th Argument mining Workshop",
+    month = jul,
+    year = "2025",
+    address = "Vienna, Austria",
+    publisher = "Association for Computational Linguistics",
+    url = "https://aclanthology.org/2025.argmining-1.16/",
+    doi = "10.18653/v1/2025.argmining-1.16",
+    pages = "168--180",
+    ISBN = "979-8-89176-258-9",
+    abstract = "Definition generation models trained on dictionary data are generally expected to produce neutral and unbiased output while capturing the contextual nuances. However, previous studies have shown that generated definitions can inherit biases from both the underlying models and the input context. This paper examines the extent to which stance-related bias in argumentative data influences the generated definitions. In particular, we train a model on a slang-based dictionary to explore the feasibility of generating persuasive definitions that concisely reflect opposing parties' understandings of contested terms. Through this study, we provide new insights into bias propagation in definition generation and its implications for definition generation applications and argument mining."
+}
+
+```