Improve model card: Add pipeline tag, correct library_name, expand details, usage, and training info

README.md

@@ -1,45 +1,45 @@
 ---
 base_model: meta-llama/Llama-3.1-8B
-library_name: peft
 datasets:
 - baartmar/nsm_dataset
-license: cc-by-nc-sa-4.0
 language:
 - en
+library_name: transformers
+license: cc-by-nc-sa-4.0
+pipeline_tag: text-generation
+tags:
+- nlp
+- paraphrase
+- semantic-analysis
+- llama
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
-A fine-tuned LLM for paraphrasing word-meanings using the natural semantic primes.
+# Model Card for DeepNSM-8B
 
+A fine-tuned Large Language Model (LLM) for paraphrasing word-meanings into Natural Semantic Metalanguage (NSM) explications, presented in the paper [Towards Universal Semantics With Large Language Models](https://arxiv.org/abs/2505.11764).
 
 ## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
-A fine-tuned LLM for paraphrasing word-meanings using the natural semantic primes.
-
+DeepNSM is a fine-tuned Large Language Model (LLM) designed for generating Natural Semantic Metalanguage (NSM) explications of word-meanings. NSM is a linguistic theory based on a universal set of semantic primes that allows any word to be paraphrased into a clear, universally translatable meaning. This work addresses the traditionally slow, manual process of creating NSM explications by leveraging LLMs. The 1B and 8B DeepNSM models introduced in the paper [Towards Universal Semantics With Large Language Models](https://arxiv.org/abs/2505.11764) outperform GPT-4o in producing accurate, cross-translatable explications, marking a significant step toward universal semantic representation with LLMs.
 
-- **Developed by:** 
-- **Model type:** Text Generation
-- **Language(s) (NLP):** English
-- **License:** cc-by-nc-sa-4.0
-- **Finetuned from model:** Llama-3.1-8B
+-   **Developed by:** Raymond Baartmans, Matthew Raffel, Rahul Vikram, Aiden Deringer, Lizhong Chen
+-   **Model type:** Text Generation, specialized in NSM explication
+-   **Language(s) (NLP):** English
+-   **License:** cc-by-nc-sa-4.0
+-   **Finetuned from model:** Llama-3.1-8B
 
-### Model Sources [optional]
+### Model Sources
 
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** https://github.com/OSU-STARLAB/DeepNSM
-- **Paper:** https://arxiv.org/abs/2505.11764
+-   **Repository:** https://github.com/OSU-STARLAB/DeepNSM
+-   **Paper:** https://arxiv.org/abs/2505.11764
+-   **Demo:** [Colab Demo](https://colab.research.google.com/drive/1kWesMSQOgKOsXxONvZyinpdgh86gDBcy?usp=drive_link)
 
 ## Uses
 
 ### Direct Use
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
 To use the DeepNSM model to generate an NSM paraphrase of a word-meaning, you should structure your prompts in the following format:
 ```
 Word: dangerous
@@ -49,160 +49,138 @@ walking outside at night is dangerous
 Paraphrase:
 ```
 
-### Downstream Use [optional]
-
-<!-- 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]
+The generated NSM explications can offer valuable applications for many natural language processing (NLP) tasks, including semantic analysis, translation, and beyond, as they reveal clear and universally translatable meanings.
 
 ### Out-of-Scope Use
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
+This model is specifically fine-tuned for generating NSM explications. It is not intended for general-purpose conversational AI, code generation, or other tasks for which it has not been explicitly trained or fine-tuned. Using it for out-of-scope applications may lead to suboptimal or irrelevant results.
 
 ## Bias, Risks, and Limitations
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
+-   **Language Specificity:** While NSM is designed for universality, the current model is primarily trained on English data. Its performance on generating explications for other languages, even if conceptually translatable, is not guaranteed without further multilingual fine-tuning.
+-   **Subjectivity in Explications:** Despite NSM's rigorous framework, human-annotated explications can sometimes have subtle variations or ambiguities. The model's output reflects the patterns learned from this data.
+-   **Generative Nature:** As a generative model, it may occasionally produce outputs that are grammatically correct but semantically inaccurate or nonsensical in the context of NSM theory.
+-   **Resource Intensive:** Running the 8B parameter model requires significant computational resources (NVIDIA GPU with >16GB VRAM), which may limit accessibility for some users.
 
 ### Recommendations
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. For critical applications, human review of generated explications is recommended. Further research into multilingual NSM explication and broader evaluation across diverse linguistic and cultural contexts would be beneficial.
 
 ## How to Get Started with the Model
 
-Use the code below to get started with the model.
+Use the code below to get started with the model. Ensure you have the `transformers` and `torch` libraries installed. A GPU with sufficient VRAM is recommended for the 8B model.
 
-[More Information Needed]
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
-## Training Details
+model_name = "baartmar/DeepNSM-8B" # or "baartmar/DeepNSM-1B"
 
-### Training Data
+# Load tokenizer and model
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    torch_dtype=torch.bfloat16, # Adjust dtype based on your GPU capabilities (e.g., torch.float16 or torch.float32)
+    device_map="auto" # Automatically distribute model across available GPUs
+)
 
-<!-- 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. -->
+# Set model to evaluation mode
+model.eval()
 
-[More Information Needed]
+# Example prompt
+prompt = """Word: dangerous
+Examples:
+don't go near the dangerous fire
+walking outside at night is dangerous
+Paraphrase:
+"""
+
+# Tokenize input
+input_ids = tokenizer.encode(prompt, return_tensors="pt").to(model.device)
+
+# Generate output
+with torch.no_grad():
+    output_ids = model.generate(
+        input_ids,
+        max_new_tokens=100, # Adjust as needed for explication length
+        temperature=0.7,    # Adjust for creativity vs. faithfulness
+        do_sample=True,     # Set to True for sampling, False for greedy decoding
+        pad_token_id=tokenizer.eos_token_id # Important for batch generation
+    )
+
+# Decode and print the generated text
+generated_text = tokenizer.decode(output_ids[0], skip_special_tokens=True)
+print(generated_text)
+```
 
-### Training Procedure
+For a more comprehensive demonstration and local inference setup, please refer to the [Colab Demo](https://colab.research.google.com/drive/1kWesMSQOgKOsXxONvZyinpdgh86gDBcy?usp=drive_link) and the [GitHub repository](https://github.com/OSU-STARLAB/DeepNSM).
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+## Training Details
 
-#### Preprocessing [optional]
+### Training Data
 
-[More Information Needed]
+The model was fine-tuned on the [baartmar/nsm_dataset](https://huggingface.co/datasets/baartmar/nsm_dataset), a tailored dataset specifically designed for training and evaluating NSM explication tasks.
 
+### Training Procedure
 
 #### 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]
+-   **Training regime:** Mixed precision (bfloat16 for computation where supported, with 4-bit quantization as indicated by `use-4bit`, `bnb-4bit-compute-dtype bfloat16`, `bnb-4bit-quant-type nf4` in the training command).
+-   **LoRA parameters:** `lora_alpha=16`, `lora_dropout=0.1`, `lora_r=64` (from `adapter_config.json`).
+-   **Optimizer:** `paged_adamw_32bit`.
+-   **Learning rate:** `2e-4` with `inverse_sqrt` scheduler and `warmup_ratio=0.03`.
+-   **Max gradient norm:** `0.3`.
+-   **Max sequence length:** `256`.
+-   **Effective batch size:** 64 (derived from `bsz 64` and `update-freq 1` in the example training command).
+-   **Number of training epochs:** `1` (as specified in the `train.py` example command, though training logs show progression over multiple virtual epochs/steps up to 10000 steps).
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+#### Speeds, Sizes, Times
 
-[More Information Needed]
+-   **Checkpoints:** The DeepNSM models are available in 1B and 8B parameter variants.
+-   **Training Time:** The training logs (`trainer_state.json`) indicate a total of `10000` training steps completed over approximately 1.85 epochs, with evaluation steps every 1000 steps. Training for the 8B model requires a moderately strong GPU (e.g., >16GB VRAM as per requirements).
+-   **Total FLOPs:** `7.13 x 10^17` (from `total_flos` in `trainer_state.json`).
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
+The models were evaluated using automatic evaluation methods and compared against GPT-4o.
 
 ### 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]
+The evaluation utilized the same [baartmar/nsm_dataset](https://huggingface.co/datasets/baartmar/nsm_dataset) used for training.
 
 #### Metrics
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
+The paper introduces specific automatic evaluation methods tailored for the NSM explication task. Details on these metrics can be found in the research paper.
 
 ### Results
 
-[More Information Needed]
-
-#### Summary
-
-
+The 1B and 8B DeepNSM models consistently outperformed GPT-4o in producing accurate, cross-translatable NSM explications, marking a significant step toward universal semantic representation with LLMs. The `trainer_state.json` shows that the `eval_mean_token_accuracy` reached `0.6975` and `eval_loss` reduced to `0.9294` by the final logged step.
 
-## Model Examination [optional]
+## Citation
 
-<!-- Relevant interpretability work for the model goes here -->
+If you find our work useful or helpful for your research and applications, please feel free to cite our paper as below:
 
-[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]
+```bibtex
+@misc{baartmans2025universalsemanticslargelanguage,
+      title={Towards Universal Semantics With Large Language Models}, 
+      author={Raymond Baartmans and Matthew Raffel and Rahul Vikram and Aiden Deringer and Lizhong Chen},
+      year={2025},
+      eprint={2505.11764},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL},
+      url={https://arxiv.org/abs/2505.11764}, 
+}
+```
 
 ## Model Card Contact
 
-[More Information Needed]
+For any questions or further information, please refer to the [GitHub repository](https://github.com/OSU-STARLAB/DeepNSM) or contact the authors listed in the paper.
+
 ### Framework versions
 
-- PEFT 0.15.2
+-   PEFT 0.15.2
+-   Transformers (compatible with current versions, e.g., >=4.33.2 based on typical model requirements)