Update README.md

README.md

@@ -12,88 +12,91 @@ library_name: adapter-transformers
 tags:
 - code
 ---
-
-T5 Command Description Generator
-This project fine-tunes a T5 model (t5-small) to generate descriptions of terminal commands based on prompts in the format "Describe the command: {name} in {source}". The model is trained on a dataset (all_commands.csv) containing command names, descriptions, and sources (e.g., cmd, linux, macos, vbscript). After fine-tuning, the model can generate descriptions for commands, such as "List information about file(s)" for ls in linux.
-Table of Contents
-
-Overview
-Dataset
-Requirements
-Setup
-Fine-Tuning the Model
-Using the Model
-Example Output
-Troubleshooting
-Future Improvements
-
-Overview
-The T5 (Text-to-Text Transfer Transformer) model is fine-tuned to map prompts like "Describe the command: ls in linux" to descriptions like "List information about file(s)". The dataset used for training is all_commands.csv, which includes commands from various environments (cmd, linux, macos, vbscript). The fine-tuned model is saved to ./new_cmd_model and can be used to generate command descriptions interactively or programmatically.
-Dataset
-The dataset (all_commands.csv) contains the following columns:
-
-name: The command name (e.g., ls, dir, chmod, MsgBox).
-description: A brief description of what the command does (e.g., "List information about file(s)").
-source: The environment the command belongs to (cmd, linux, macos, vbscript).
+# T5 Command Description Generator
+
+This project fine-tunes a T5 model (`t5-small`) to generate descriptions of terminal commands based on prompts in the format "Describe the command: {name} in {source}". The model is trained on a dataset (`all_commands.csv`) containing command names, descriptions, and sources (e.g., `cmd`, `linux`, `macos`, `vbscript`). After fine-tuning, the model can generate descriptions for commands, such as "List information about file(s)" for `ls` in `linux`.
+
+## Table of Contents
+- [Overview](#overview)
+- [Dataset](#dataset)
+- [Requirements](#requirements)
+- [Setup](#setup)
+- [Fine-Tuning the Model](#fine-tuning-the-model)
+- [Using the Model](#using-the-model)
+- [Example Output](#example-output)
+- [Troubleshooting](#troubleshooting)
+- [Future Improvements](#future-improvements)
+
+## Overview
+The T5 (Text-to-Text Transfer Transformer) model is fine-tuned to map prompts like "Describe the command: ls in linux" to descriptions like "List information about file(s)". The dataset used for training is `all_commands.csv`, which includes commands from various environments (`cmd`, `linux`, `macos`, `vbscript`). The fine-tuned model is saved to `./new_cmd_model` and can be used to generate command descriptions interactively or programmatically.
+
+## Dataset
+The dataset (`all_commands.csv`) contains the following columns:
+- `name`: The command name (e.g., `ls`, `dir`, `chmod`, `MsgBox`).
+- `description`: A brief description of what the command does (e.g., "List information about file(s)").
+- `source`: The environment the command belongs to (`cmd`, `linux`, `macos`, `vbscript`).
 
 Example entries:
+```
 name,description,source
 ls,List information about file(s),linux
 dir,Display a list of files and folders,cmd
 chmod,Change access permissions,macos
 MsgBox,Display a dialogue box message,vbscript
+```
 
 The dataset is split into 80% training and 20% validation sets for fine-tuning.
-Requirements
-
-Python 3.8+
-Libraries:
-transformers
-torch
-sentencepiece
-datasets
-
 
-CUDA-enabled GPU (optional, for faster training; fp16=True in the script enables mixed precision if available)
-Dataset file: all_commands.csv (place in the project directory)
+## Requirements
+- Python 3.8+
+- Libraries:
+  - `transformers`
+  - `torch`
+  - `sentencepiece`
+  - `datasets`
+- CUDA-enabled GPU (optional, for faster training; `fp16=True` in the script enables mixed precision if available)
+- Dataset file: `all_commands.csv` (place in the project directory)
 
 Install dependencies:
+```bash
 pip install transformers torch sentencepiece datasets
-
-Setup
-
-Activate the Environment:Ensure you're in a Python environment with the required libraries. For example, using Conda:
-conda activate safetensor_new
-
-
-Prepare the Dataset:Place all_commands.csv in the project directory (e.g., C:\app\dataset).
-
-Directory Structure:
-C:\app\dataset\
-├── all_commands.csv
-├── new_cmd_model\ (created after fine-tuning)
-└── fine_tune_script.py
-
-
-
-Fine-Tuning the Model
-The fine-tuning script (fine_tune_script.py) trains a t5-small model on the all_commands.csv dataset to generate command descriptions.
-Script Overview
-
-Model: t5-small (can be upgraded to t5-base for better performance).
-Input Prompt: "Describe the command: {name} in {source}" (e.g., "Describe the command: ls in linux").
-Output: The command’s description (e.g., "List information about file(s)").
-Training Parameters:
-Epochs: 3
-Learning rate: 5e-5
-Batch size: 8
-Output directory: ./new_cmd_model
-Mixed precision training: Enabled if CUDA is available
-
-
-
-Running the Script
-Save the following script as fine_tune_script.py and run it:
+```
+
+## Setup
+1. **Activate the Environment**:
+   Ensure you're in a Python environment with the required libraries. For example, using Conda:
+   ```bash
+   conda activate safetensor_new
+   ```
+
+2. **Prepare the Dataset**:
+   Place `all_commands.csv` in the project directory (e.g., `C:\app\dataset`).
+
+3. **Directory Structure**:
+   ```
+   C:\app\dataset\
+   ├── all_commands.csv
+   ├── new_cmd_model\ (created after fine-tuning)
+   └── fine_tune_script.py
+   ```
+
+## Fine-Tuning the Model
+The fine-tuning script (`fine_tune_script.py`) trains a `t5-small` model on the `all_commands.csv` dataset to generate command descriptions.
+
+### Script Overview
+- **Model**: `t5-small` (can be upgraded to `t5-base` for better performance).
+- **Input Prompt**: "Describe the command: {name} in {source}" (e.g., "Describe the command: ls in linux").
+- **Output**: The command’s description (e.g., "List information about file(s)").
+- **Training Parameters**:
+  - Epochs: 3
+  - Learning rate: 5e-5
+  - Batch size: 8
+  - Output directory: `./new_cmd_model`
+  - Mixed precision training: Enabled if CUDA is available
+
+### Running the Script
+Save the following script as `fine_tune_script.py` and run it:
+```python
 from transformers import T5ForConditionalGeneration, T5Tokenizer, Trainer, TrainingArguments
 from datasets import load_dataset
 import torch
@@ -151,15 +154,21 @@ trainer.train()
 model.save_pretrained("./new_cmd_model")
 tokenizer.save_pretrained("./new_cmd_model")
 print("Fine-tuning complete. Model saved to './new_cmd_model'.")
+```
 
 Run the script:
+```bash
 python fine_tune_script.py
+```
+
+This will train the model and save it to `./new_cmd_model`.
 
-This will train the model and save it to ./new_cmd_model.
-Using the Model
+## Using the Model
 After fine-tuning, you can use the model to generate command descriptions with prompts like "Describe the command: {name} in {source}". Below is a script to load and use the model interactively or programmatically.
-Usage Script
-Save the following as use_t5_command_description.py:
+
+### Usage Script
+Save the following as `use_t5_command_description.py`:
+```python
 import os
 from transformers import T5ForConditionalGeneration, T5Tokenizer
 import torch
@@ -239,12 +248,16 @@ while True:
     print("-" * 50)
 
 print("Exiting interactive mode.")
+```
 
 Run the script:
+```bash
 python use_t5_command_description.py
+```
 
-Example Output
+## Example Output
 After fine-tuning and running the usage script, you should see output like:
+```
 [2025-09-04 11:50:00] Model and tokenizer loaded successfully.
 
 Generated Descriptions:
@@ -259,4 +272,58 @@ Description: List information about file(s)
 Command: dir (cmd)
 Description: Display a list of files and folders
 --------------------------------------------------
+[2025-09-04 11:50:03] Input prompt: Describe the command: chmod in macos
+[2025-09-04 11:50:03] Using device: cuda
+Command: chmod (macos)
+Description: Change access permissions
+--------------------------------------------------
+[2025-09-04 11:50:04] Input prompt: Describe the command: MsgBox in vbscript
+[2025-09-04 11:50:04] Using device: cuda
+Command: MsgBox (vbscript)
+Description: Display a dialogue box message
+--------------------------------------------------
+
+Interactive Mode: Enter a command and source to get its description.
+Valid sources: cmd, linux, macos, vbscript
+Type 'exit' to quit.
+
+Enter command name (or 'exit' to quit): ping
+Enter source (e.g., cmd, linux, macos, vbscript): linux
+[2025-09-04 11:50:05] Input prompt: Describe the command: ping in linux
+[2025-09-04 11:50:05] Using device: cuda
+Command: ping (linux)
+Description: Test a network connection
+--------------------------------------------------
+Enter command name (or 'exit' to quit): exit
+Exiting interactive mode.
+```
+
+## Troubleshooting
+- **Empty Descriptions**:
+  - Ensure `all_commands.csv` has valid entries with no missing descriptions.
+  - Increase `num_train_epochs` to 5–10 or use `t5-base` for better performance.
+  - Check training logs in `./new_cmd_model` for high loss values.
+- **Model Loading Issues**:
+  - Verify the model saved correctly in `./new_cmd_model`.
+  - Try loading a checkpoint (e.g., `./new_cmd_model/checkpoint-XXX`) if issues persist.
+- **Environment Errors**:
+  - Ensure dependencies are installed: `pip install transformers torch sentencepiece datasets`.
+  - For CUDA errors, ensure your GPU drivers are up-to-date or set `fp16=False` in the training script.
+- **Deprecation Warning**:
+  - The script uses `evaluation_strategy`, which is deprecated. Update to `eval_strategy` in newer `transformers` versions:
+    ```python
+    training_args = TrainingArguments(
+        output_dir="./new_cmd_model",
+        eval_strategy="epoch",
+        ...
+    )
+    ```
+
+## Future Improvements
+- **Augment Dataset**: Add more command descriptions or variations to improve generalization.
+- **Use Larger Model**: Switch to `t5-base` for better accuracy (update `model_name` and retrain).
+- **Extend Task**: Modify to generate commands from task descriptions (e.g., "List files in linux" → `ls`) by retraining with swapped inputs/outputs.
+- **Command Execution**: Add functionality to execute generated commands (requires careful validation for security).
+
+For questions about xAI’s API, visit [https://x.ai/api](https://x.ai/api).
 [2025-09-04