Update README.md

README.md

@@ -1,202 +1,240 @@
 ---
 language:
-  language: en
-  license: mit
+  - en
+  - fr
+  - multilingual
+license: mit
 ---
 
-# model-card-testing
+# Model Card for model-card-testing
 
-<details>
-  <summary>Expand policymaker version</summary>
-  
-  *Pretend we decide upon set of info from the full model card that we think is relevant to policymakers, for example...* 
-  
-  ## [MODEL NAME] Model Card for Policymakers
-  
-  ### Model Details
-  
-  This model was developed by XYZ and can be used for XYZ. It was introduced in this paper and the code is available here.
-  
-  ### Uses 
-  
-  This model should be used for XYZ tasks and should not be used for XYZ tasks. 
-  
-  ### Risks, Limitations and Bias
-  
-  Some of the risks associated with using this model include XYZ.
-  
-</details>
+<!-- Provide a quick summary of what the model is/does. [Optional] -->
+This is a placeholder summary.
 
-<details>
-  <summary>Expand researcher version</summary>
-  
-  *Pretend we decide upon set of info from the full model card that we think is relevant to researchers and put that here...* 
-  
-</details>
 
 <details>
-  <summary>Expand developer version</summary>
-  
-   *Pretend we decide upon set of info from the full model card that we think is relevant to developers and put that here...* 
-    
+<summary> Click to expand policymaker version of model card </summary>
+
+# Table of Contents 
+
+1. [Model Details](#model-details)
+2. [Uses](#uses)
+3. [Bias, Risks, and Limitations](#bias-risks-and-limitations)
+4. [Model Examination](#model-examination)
+5. [Environmental Impact](#environmental-impact)
+6. [Citation](#citation)
+7. [Glossary](#glossary-optional)
+8. [More Information](#more-information-optional)
+9. [Model Card Authors](#model-card-authors-optional)
+10. [Model Card Contact](#model-card-contact)
+
 </details>
 
-<details>
-  <summary>Expand full version</summary>
+#  Table of Contents
 
-## Table of Contents
 1. [Model Details](#model-details)
-2. [How To Get Started With the Model](#how-to-get-started-with-the-model)
-3. [Uses](#uses)
-4. [Limitations](#limitations)
-5. [Training](#training)
-6. [Evaluation Results](#evaluation-results)
+2. [Uses](#uses)
+3. [Bias, Risks, and Limitations](#bias-risks-and-limitations)
+4. [Training Details](#training-details)
+5. [Evaluation](#evaluation)
+6. [Model Examination](#model-examination)
 7. [Environmental Impact](#environmental-impact)
-8. [Citation Information](#citation-information)
+8. [Technical Specifications](#technical-specifications-optional)
+9. [Citation](#citation)
+10. [Glossary](#glossary-optional)
+11. [More Information](#more-information-optional)
+12. [Model Card Authors](#model-card-authors-optional)
+13. [Model Card Contact](#model-card-contact)
+14. [How To Get Started With the Model](#how-to-get-started-with-the-model)
+
+
+# Model Details
+
+## Model Description
+
+<!-- Provide a longer summary of what this model is/does. -->
+
+
+- **Developed by:** More information needed
+- **Shared by [Optional]:** More information needed
+- **Model type:** Language model
+- **Language(s) (NLP):** More information needed
+- **License:** More information needed
+- **Related Models:** fake_model1, fake_model2
+    - **Parent Model:** More information needed
+- **Resources for more information:** More information needed
+
+    - [Associated Paper](https://huggingface.co) 
+    - [Blog Post](https://huggingface.co)
+
+# 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. -->
+<!-- If the user enters content, print that. If not, but they enter a task in the list, use that. If neither, say "more info needed." -->
+
+The model can be used for text generation.
+
+
+## Downstream Use [Optional]
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+<!-- If the user enters content, print that. If not, but they enter a task in the list, use that. If neither, say "more info needed." -->
+ 
+To learn more about this task and potential downstream uses, see the Hugging Face [text generation docs](https://huggingface.co/tasks/text-generation)
+
 
-## Model Details
+## Out-of-Scope Use
 
-model-card-testing is a distilled language modelthat can be used for text generation. Users of this model card should also consider information about the design, training, and limitations of gpt2.
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+<!-- If the user enters content, print that. If not, but they enter a task in the list, use that. If neither, say "more info needed." -->
 
-- **Developed by:** author1, author2
-- **Model type:** testing type
-- **Language(s):**  # not working right now
-- **License:**  # not working right now
-- **Model Description:** testing description
-- **Related Models:** 
-    - **Parent Model**: gpt2
-    - **Sibling Models**: TO DO (could we do this automatically somehow?)
+The model should not be used to intentionally create hostile or alienating environments for people. The model was not trained to be factual or true representations of people or events, and therefore using the models to generate such content is out-of-scope for the abilities of this model.
 
 
-## How to Get Started with the Model 
+# Bias, Risks, and Limitations
 
-Use the code below to get started with the model.  model-card-testing can be used directly with a pipeline for text generation. 
-Since the generation relies on some randomness, we set a seed for reproducibility:
-```python
->>> from transformers import pipeline, set_seed
->>> generator = pipeline('text-generation', model='model-card-testing')
->>> set_seed(42)
->>> generator("Hello, I'm a language model," max_length=20, num_return_sequences=5)
-```
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
 
+Significant research has explored bias and fairness issues with language models (see, e.g., [Sheng et al. (2021)](https://aclanthology.org/2021.acl-long.330.pdf) and [Bender et al. (2021)](https://dl.acm.org/doi/pdf/10.1145/3442188.3445922)). Predictions generated by the model may include disturbing and harmful stereotypes across protected classes; identity characteristics; and sensitive, social, and occupational groups.
 
-Here is how to use this model to get the features of a given text in Pytorch: 
 
-NOTE: This will need customization/fixing.
+## Recommendations
 
-```python
-from transformers import GPT2Tokenizer, GPT2Model
-tokenizer = GPT2Tokenizer.from_pretrained('model-card-testing')
-model = GPT2Model.from_pretrained('model-card-testing')
-text = "Replace me by any text you'd like."
-encoded_input = tokenizer(text, return_tensors='pt')
-output = model(**encoded_input)
-```
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
 
-and in TensorFlow: 
 
-NOTE: This will need customization/fixing.
+Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recomendations.
 
-```python
-from transformers import GPT2Tokenizer, TFGPT2Model
-tokenizer = GPT2Tokenizer.from_pretrained('model-card-testing')
-model = TFGPT2Model.from_pretrained('model-card-testing')
-text = "Replace me by any text you'd like."
-encoded_input = tokenizer(text, return_tensors='tf')
-output = model(encoded_input)
-```
 
-## Uses
-LLMs are intended to be used for language generation or as a pretrained base model that can be further fine-tuned for specific tasks. Use cases below are not exhaustive.
+# Training Details
 
-#### Direct Use
-This model can be used for:
-- Text generation
-- Exploring characterisitics of language generated by a language model 
-    - Examples: Cloze tests, counterfactuals, generations with reframings
+## Training Data
 
-#### Downstream Use
-Tasks that leverage language models, including: 
-- Information Extraction, Question Answering, Summarization
-- Writing assistance: Grammar assistance, autocompletion (for normal prose or code)
-- Creative writing and art: exploring the generation of creative, fictional texts; aiding creation of poetry and other literary art.
-- Entertainment: Creation of games, chat bots, and amusing generations.
+<!-- This should link to a Data 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. -->
 
-#### Misuse and Out-of-scope Use
-Using the model in high-stakes settings is out of scope for this model.  The model is not designed for critical decisions nor uses with any material consequences on an individual's livelihood or wellbeing. The model outputs content that appears factual but is not correct.
+More information on training data needed
 
-## Limitations
 
-**CONTENT WARNING: Readers should be aware this section contains content that is disturbing, offensive, and can propogate historical and current stereotypes.**
+## Training Procedure
 
-Significant research has explored bias and fairness issues with models for language generation (see, e.g., [Sheng et al. (2021)](https://aclanthology.org/2021.acl-long.330.pdf) and [Bender et al. (2021)](https://dl.acm.org/doi/pdf/10.1145/3442188.3445922)). This model also has persistent bias issues, as highlighted in these demonstrative examples below. Note that these examples are not a comprehensive stress-testing of the model. Readers considering using the model should consider more rigorous evaluations of the model depending on their use case and context.
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
 
+### Preprocessing
 
-The impact of model compression techniques, such as knowledge distillation, on bias and fairness issues associated with language models is an active area of research. For example:
-- [Silva, Tambwekar and Gombolay (2021)](https://aclanthology.org/2021.naacl-main.189.pdf) find that distilled versions of BERT and RoBERTa consistently exhibit statistically significant bias (with regard to gender and race) with effect sizes larger than the teacher models.
-- [Xu and Hu (2022)](https://arxiv.org/pdf/2201.08542.pdf) find that distilled versions of GPT-2 showed consistent reductions in toxicity and bias compared to the teacher model (see the paper for more detail on metrics used to define/measure toxicity and bias).
-- [Gupta et al. (2022)](https://arxiv.org/pdf/2203.12574.pdf) find that DistilGPT2 exhibits greater gender disparities than GPT-2 and propose a technique for mitigating gender bias in distilled language models like DistilGPT2.
+More information needed
 
+### Speeds, Sizes, Times
 
+<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
 
+More information needed
+ 
+# Evaluation
 
-NOTE: This code will need customization/fixing.
+<!-- This section describes the evaluation protocols and provides the results. -->
 
+## Testing Data, Factors & Metrics
 
-```python
->>> from transformers import pipeline, set_seed
->>> generator = pipeline('text-generation', model='model-card-testing')
->>> set_seed(48)
->>> generator("The White man worked as a", max_length=20, num_return_sequences=3)
+### Testing Data
 
->>> set_seed(48)
->>> generator("The Black man worked as a", max_length=20, num_return_sequences=3)
-```
+<!-- This should link to a Data Card if possible. -->
 
+More information needed
 
 
+### Factors
 
-## Training 
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
 
-#### Training Data
+More information needed
 
-model-card-testing was trained using . See the  data card for additional information. 
+### Metrics
 
-#### Training Procedure
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
 
-Preprocessing, hardware used, hyperparameters...
+More information needed
 
-## Evaluation Results
+## Results 
 
-This model achieves the following results:
+More information needed
 
-NOTE: This will need customization.
+# Model Examination
 
+More information needed
 
-| Dataset  | LAMBADA | LAMBADA | CBT-CN | CBT-NE | WikiText2 | PTB    | enwiki8 | text8  | WikiText103 | 1BW   |
-|:--------:|:-------:|:-------:|:------:|:------:|:---------:|:------:|:-------:|:------:|:-----------:|:-----:|
-| (metric) | (PPL)   | (ACC)   | (ACC)  | (ACC)  | (PPL)     | (PPL)  | (BPB)   | (BPC)  | (PPL)       | (PPL) |
-|          |         |         |        |        |           |        |         |        |             |       |
+# 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
 
-## Environmental Impact
+# Technical Specifications [optional]
 
-You can estimate carbon emissions using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700)
+## Model Architecture and Objective
 
-- **Hardware Type:** 
-- **Hours used:** 
-- **Cloud Provider:** 
-- **Compute Region:** 
-- **Carbon Emitted** *(Power consumption x Time x Carbon produced based on location of power grid)*:
+More information needed
 
-## Citation Information
+## Compute Infrastructure
+
+More information needed
+
+### Hardware
+
+More information needed
+
+### Software
+
+More information needed
+
+# Citation
+
+<!-- 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]
+
+<!-- This section provides another layer of transparency and accountability. Whose views is this model card representing? How many voices were included in its construction? Etc. -->
+
+More information needed
+
+# Model Card Contact
+
+More information needed
+
+# How to Get Started with the Model
+
+Use the code below to get started with the model.
+
+<details>
+<summary> Click to expand </summary>
 
-```bibtex
-@inproceedings{...,
-  year={2020}
-}
-```
+More information needed
 
 </details>