Update README.md

README.md

@@ -1,177 +1,244 @@
 ---
 library_name: transformers
-base_model:
-- facebook/bart-base
+license: apache-2.0
+base_model: facebook/bart-base
+datasets:
+- eilamc14/wikilarge-clean
+language:
+- en
+tags:
+- bart
+- text-simplification
+- WikiLarge
+model-index:
+- name: bart-base-text-simplification
+  results:
+  - task:
+      type: text2text-generation
+      name: Text Simplification
+    dataset:
+      name: WikiLarge Cleaned
+      type: eilamc14/wikilarge-clean
+      split: test
+    metrics:
+    - type: SARI
+      value: 36.13
+    - type: FKGL
+      value: 8.50
+    - type: BERTScore
+      value: 85.57
+    - type: LENS
+      value: 43.88
 ---
 
 # Model Card for Model ID
 
-<!-- Provide a quick summary of what the model is/does. -->
-
-
+This is one of the models fine-tuned on text simplification for [Simplify This](https://github.com/eilamc14/Simplify-This) project.
 
 ## 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.
+Fine-tuned **sequence-to-sequence (encoder–decoder) Transformer** for **English text simplification**.  
+Trained on the dataset **`eilamc14/wikilarge-clean`** (cleaned WikiLarge-style pairs).
 
-- **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 type:** Seq2Seq Transformer (encoder–decoder)
+- **Language (NLP):** English
+- **License:** `apache-2.0`
+- **Finetuned from model:** `facebook/bart-base`
 
-### Model Sources [optional]
+### Model Sources
 
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+- **Repository (code):** https://github.com/eilamc14/Simplify-This
+- **Dataset:** https://huggingface.co/datasets/eilamc14/wikilarge-clean
+- **Paper [optional]:** —
+- **Demo [optional]:** —
 
 ## Uses
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
 ### Direct Use
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+The model is intended for **English text simplification**.
 
-[More Information Needed]
+- **Input format:** `Simplify: <complex sentence>`
+- **Output:** `<simplified sentence>`
 
-### Downstream Use [optional]
+**Typical uses**
+- Research on automatic text simplification
+- Benchmarking against other simplification systems
+- Demos/prototypes that require simpler English rewrites
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+### Downstream Use
 
-[More Information Needed]
+This repository already contains a **fine-tuned** model specialized for text simplification.
+
+Further fine-tuning is **optional** and mainly relevant when:
+- Adapting to a markedly different domain (e.g., medical/legal/news)
+- Addressing specific failure modes (e.g., over/under-simplification, factual drops)
+- Distilling/quantizing for deployment constraints
+
+When fine-tuning further, keep the same input convention: `Simplify: <...>`.
 
 ### Out-of-Scope Use
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+Not intended for:
+- Tasks unrelated to simplification (dialogue, translation etc.)
+- Production use without additional safety filtering (no toxicity/bias mitigation)
+- Languages other than English
+- High-stakes settings (legal/medical advice, safety-critical decisions)
 
-[More Information Needed]
 
 ## Bias, Risks, and Limitations
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+The model was trained on **Wikipedia and Simple English Wikipedia** alignments (via WikiLarge).  
+As a result, it inherits the characteristics and limitations of this data:
 
-[More Information Needed]
+- **Domain bias:** Simplifications may reflect encyclopedic style; performance may degrade on informal, technical, or domain-specific text (e.g., medical/legal/news).
+- **Content bias:** Wikipedia content itself contains biases in coverage, cultural perspective, and phrasing. Simplified outputs may reflect or amplify these.
+- **Simplification quality:** The model may:
+  - Over-simplify (drop important details)
+  - Under-simplify (retain complex phrasing)
+  - Produce ungrammatical or awkward rephrasings
+- **Language limitation:** Only suitable for English. Applying to other languages is unsupported.
+- **Safety limitation:** The model has not been aligned to avoid toxic, biased, or harmful content. If the input text contains such content, the output may reproduce or modify it without safeguards.
 
-### Recommendations
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+### Recommendations
 
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+- **Evaluation required:** Always evaluate the model in the target domain before deployment. Benchmark simplification quality (e.g., with SARI, FKGL, BERTScore, LENS, human evaluation).
+- **Human oversight:** Use human-in-the-loop review for applications where meaning preservation is critical (education, accessibility tools, etc.).
+- **Attribution:** Preserve source attribution where required (Wikipedia → CC BY-SA).
+- **Not for high-stakes use:** Avoid legal, medical, or safety-critical applications without extensive validation and domain adaptation.
 
 ## How to Get Started with the Model
 
-Use the code below to get started with the model.
+Load the model and tokenizer directly from the Hugging Face Hub:
 
-[More Information Needed]
+```python
+from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
+
+model_id = "eilamc14/bart-base-text-simplification"
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForSeq2SeqLM.from_pretrained(model_id)
+
+# Example input
+PREFIX = "Simplify: "
+text = "The committee deemed the proposal unnecessarily complicated."
+
+# Tokenize and generate
+inputs = tokenizer(PREFIX+text, return_tensors="pt")
+outputs = model.generate(**inputs, max_new_tokens=64, num_beams=4)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
 
 ## 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]
+[WikiLarge-clean](https://huggingface.co/datasets/eilamc14/wikilarge-clean) Dataset
 
 ### Training Procedure
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+- **Hardware:** NVIDIA L4 GPU on Google Colab
+- **Objective:** Standard sequence-to-sequence cross-entropy loss
+- **Training type:** Full fine-tuning of all parameters (no LoRA/PEFT used)
+- **Batching:** Dynamic padding with Hugging Face `Trainer` / PyTorch DataLoader
+- **Evaluation:** Monitored on the `validation` split with metrics (SARI and identical_ratio)
+- **Stopping criteria:** Early stopping CallBack based on validation performance
+  
+#### Preprocessing
 
-#### Preprocessing [optional]
+The dataset was preprocessed by prefixing each source sentence with **"Simplify: "** and tokenizing both the source (inputs) and target (labels).
 
-[More Information Needed]
+#### Memory & Checkpointing
 
+To reduce VRAM during training, gradient checkpointing was enabled and the KV cache was disabled:
 
-#### Training Hyperparameters
+```python
+model.config.use_cache = False          # required when using gradient checkpointing
+model.gradient_checkpointing_enable()   # saves memory at the cost of extra compute
+```
 
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+**Notes**
+- Disabling `use_cache` avoids warnings/conflicts with gradient checkpointing and reduces memory usage in the forward pass.
+- Gradient checkpointing trades **GPU memory ↓** for **training speed ↓** (extra recomputation).
+- For **inference/evaluation**, re-enable the cache for faster generation:
 
-#### Speeds, Sizes, Times [optional]
+```python
+model.config.use_cache = True
+```
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+#### Training Hyperparameters
 
-[More Information Needed]
+The models were trained with Hugging Face `Seq2SeqTrainingArguments`.  
+Hyperparameters varied slightly across models and runs to optimize, and full logs (batch size, steps, exact LR schedule) were not preserved.  
+Below are the **typical defaults** used:
+
+- **Epochs:** 5  
+- **Evaluation strategy:** every 300 steps  
+- **Save strategy:** every 300 steps (keep best model, `eval_loss` as criterion)  
+- **Learning rate:** ~3e-5  
+- **Batch size:** ~8-64 , depends on model size
+- **Optimizer:** `adamw_torch_fused`
+- **Precision:** bf16 
+- **Generation config (during eval):** `max_length=128`, `num_beams=4`, `predict_with_generate=True`  
+- **Other settings:**  
+  - Weight decay: 0.01  
+  - Label smoothing: 0.1  
+  - Warmup ratio: 0.1  
+  - Max grad norm: 0.5  
+  - Dataloader workers: 8 (L4 GPU)  
+
+> Because hyperparameters were adjusted between runs and not all were logged, exact reproduction may differ slightly.
 
 ## 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]
+### Testing Data
+
+- [**ASSET**](https://huggingface.co/datasets/facebook/asset) (test subset)
+- [**MEDEASI**](https://huggingface.co/datasets/cbasu/Med-EASi) (test subset)
+- [**OneStopEnglish**](https://github.com/nishkalavallabhi/OneStopEnglishCorpus) (advanced → elementary)
+
+### Metrics
+
+- **Identical ratio** — share of outputs identical to the source, both normalized by basic, language-agnostic: strip, NFKC, collapse spaces
+- **Identical ratio (ci)** — case insensitive identical ratio
+- **SARI** — main simplification metric (higher is better)
+- **FKGL** — readability grade level (lower is simpler)
+- **BERTScore (F1)** — semantic similarity (higher is better)
+- **LENS** — composite simplification quality score (higher is better)
+  
+### Generation Arguments
+
+```python
+gen_args = dict(
+    max_new_tokens=64,
+    num_beams=4,
+    length_penalty=1.0,
+    no_repeat_ngram_size=3,
+    early_stopping=True,
+    do_sample=False,
+)
+```
 
 ### Results
 
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
+| Dataset | Identical ratio | Identical ratio (ci) | SARI | FKGL | BERTScore | LENS |
+|---|---:|---:|---:|---:|---:|---:|
+| **ASSET** | 0.00 | 0.00 | 36.13 | 8.50 | 85.57 | 43.88 |
+| **MEDEASI** | 0.02 | 0.02 | 33.47 | 10.49 | 44.16 | 35.33 |
+| **OneStopEnglish** | 0.00 | 0.00 | 37.45 | 8.08 | 75.46 | 41.18 |
 
-<!-- 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]
+- **Hardware Type:** Single NVIDIA L4 GPU (Google Colab)
+- **Hours used:** Approx. 5–10
+- **Cloud Provider:** Google Cloud (via Colab)
+- **Compute Region:** Unknown (Google Colab dynamic allocation)
+- **Carbon Emitted:** Estimated to be very low (< a few kg CO₂eq), since training was limited to a single GPU for a small number of hours.
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+## Citation
 
 **BibTeX:**
 
@@ -179,22 +246,4 @@ Carbon emissions can be estimated using the [Machine Learning Impact calculator]
 
 **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]