Update README.md

README.md

@@ -1,199 +1,218 @@
 ---
 library_name: transformers
-tags: []
+license: apache-2.0
+base_model: t5-base
+tags:
+- text2text-generation
+- music
+- spotify
+- audio-features
+- t5
+language:
+- en
+datasets:
+- custom
+metrics:
+- mae
+- mse
+- correlation
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
-
+# T5 Spotify Features Generator
 
+A fine-tuned T5-base model that generates Spotify audio features from natural language music descriptions.
 
 ## 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.
-
-- **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]
+This model converts natural language descriptions of music preferences into Spotify audio feature values. For example, "energetic dance music for a party" becomes `"danceability": 0.9, "energy": 0.9, "valence": 0.9`.
 
-### Model Sources [optional]
+- **Developed by:** afsagag
+- **Model type:** Text-to-Text Generation (T5)
+- **Language(s):** English
+- **License:** Apache-2.0
+- **Finetuned from model:** [t5-base](https://huggingface.co/t5-base)
 
-<!-- Provide the basic links for the model. -->
+### Model Sources
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+- **Repository:** https://huggingface.co/afsagag/t5-spotify-features-generator
 
 ## 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. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
+Generate Spotify audio features from music descriptions for:
+- Music recommendation systems
+- Playlist generation
+- Music discovery applications
+- Audio feature prediction research
+
+```python
+from transformers import T5ForConditionalGeneration, T5Tokenizer
+import torch
+
+# Load model and tokenizer
+model = T5ForConditionalGeneration.from_pretrained("afsagag/t5-spotify-features-generator")
+tokenizer = T5Tokenizer.from_pretrained("afsagag/t5-spotify-features-generator")
+
+def generate_spotify_features(prompt, model, tokenizer):
+    input_text = f"prompt: {prompt}"
+    input_ids = tokenizer(input_text, return_tensors="pt", max_length=256, truncation=True).input_ids
+    
+    with torch.no_grad():
+        outputs = model.generate(
+            input_ids,
+            max_length=256,
+            num_beams=4,
+            early_stopping=True,
+            do_sample=False,
+            pad_token_id=tokenizer.pad_token_id,
+            eos_token_id=tokenizer.eos_token_id
+        )
+    
+    result = tokenizer.decode(outputs[0], skip_special_tokens=True)
+    return result
+
+# Example usage
+prompt = "I need energetic dance music for a party"
+features = generate_spotify_features(prompt, model, tokenizer)
+print(features)  # Output: "danceability": 0.9, "energy": 0.9, "valence": 0.9
+```
 
 ### Out-of-Scope Use
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
+- Generating actual audio or music files
+- Non-English music descriptions (model trained on English only)
+- Precise music recommendation without human oversight
+- Applications requiring guaranteed JSON format output
 
 ## Bias, Risks, and Limitations
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
+- **Training Data Bias:** Reflects patterns in the training dataset, may not represent all musical styles or cultural contexts
+- **JSON Format Issues:** May occasionally generate incomplete JSON objects
+- **Subjective Features:** Audio features like "valence" and "energy" are subjective and may not align with all listeners' perceptions
+- **Western Music Bias:** Training focused on Western musical concepts and terminology
 
 ### 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.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
+- Validate generated features against expected ranges
+- Use as a starting point rather than definitive feature values
+- Consider cultural and stylistic diversity when applying to diverse music catalogs
+- Implement post-processing to ensure valid JSON output if required
 
 ## 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]
+Custom dataset of 4,206 examples pairing natural language music descriptions with Spotify audio features:
+- **Training set:** 3,364 examples
+- **Validation set:** 421 examples  
+- **Test set:** 421 examples
 
 ### Training Procedure
 
-<!-- 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]
+- **Training epochs:** 5
+- **Learning rate:** 2e-4
+- **Batch size:** 32 (train), 16 (eval)
+- **Gradient accumulation steps:** 2
+- **LR scheduler:** Cosine with 5% warmup
+- **Max sequence length:** 256 tokens
+- **Training regime:** bf16 mixed precision
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+#### Speeds, Sizes, Times
 
-[More Information Needed]
+- **Training time:** ~58 minutes
+- **Final training loss:** 0.5579
+- **Model size:** ~892MB
 
 ## 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]
+Same distribution as training data: natural language music descriptions paired with Spotify audio features.
 
 #### Metrics
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
+- Mean Absolute Error (MAE) between predicted and actual feature values
+- Mean Squared Error (MSE) for regression accuracy
+- Pearson correlation coefficients for individual features
+- Valid JSON ratio for output format correctness
 
 ### Results
 
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
+The model demonstrates strong semantic understanding of musical concepts:
 
-[More Information Needed]
+| Prompt | Generated Features |
+|--------|-------------------|
+| "I need energetic dance music for a party" | `"danceability": 0.9, "energy": 0.9, "valence": 0.9` |
+| "Play calm acoustic songs for studying" | `"acousticness": 0.8, "energy": 0.2, "valence": 0.2` |
+| "Upbeat music for working out" | `"danceability": 0.7, "energy": 0.8, "valence": 0.7` |
+| "Relaxing instrumental background music" | `"acousticness": 0.3, "energy": 0.2, "instrumentalness": 0.8, "valence": 0.2` |
+| "Happy pop music for driving" | `"danceability": 0.8, "energy": 0.8, "valence": 0.8` |
 
-## 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]
+## Technical Specifications
 
 ### Model Architecture and Objective
 
-[More Information Needed]
+- **Base Architecture:** T5 (Text-To-Text Transfer Transformer)
+- **Model Size:** t5-base (220M parameters)
+- **Objective:** Sequence-to-sequence generation of audio features from text descriptions
+- **Input Format:** `"prompt: {natural_language_description}"`
+- **Output Format:** JSON-style audio feature values
 
 ### Compute Infrastructure
 
-[More Information Needed]
-
 #### Hardware
 
-[More Information Needed]
+- GPU with CUDA support
+- Mixed precision training (bf16)
 
 #### 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]
+- PyTorch with CUDA
+- Transformers library
+- Datasets library for data processing
+
+## Spotify Audio Features Reference
+
+The model generates these Spotify audio features:
+
+- **danceability** (0.0-1.0): How suitable a track is for dancing
+- **energy** (0.0-1.0): Perceptual measure of intensity and power  
+- **valence** (0.0-1.0): Musical positivity (happy vs sad)
+- **acousticness** (0.0-1.0): Confidence measure of acoustic nature
+- **instrumentalness** (0.0-1.0): Predicts absence of vocals
+- **speechiness** (0.0-1.0): Presence of spoken words
+- **liveness** (0.0-1.0): Presence of live audience
+- **loudness** (dB): Overall loudness, typically -60 to 0 dB
+- **tempo** (BPM): Estimated beats per minute
+- **duration_ms**: Track duration in milliseconds
+- **key** (0-11): Musical key (C=0, C♯/D♭=1, etc.)
+- **mode** (0-1): Modality (0=minor, 1=major)
+- **time_signature** (3-7): Time signature
+- **popularity** (0-100): Spotify popularity score
+
+## Citation
+
+```bibtex
+@misc{t5-spotify-features-generator,
+  author = {afsagag},
+  title = {T5 Spotify Features Generator: Fine-tuned T5 for Music Feature Prediction from Natural Language},
+  year = {2025},
+  publisher = {Hugging Face},
+  howpublished = {\url{https://huggingface.co/afsagag/t5-spotify-features-generator}}
+}
+```
+
+## Model Card Authors
+
+afsagag
 
 ## Model Card Contact
 
-[More Information Needed]
+Contact through Hugging Face profile: [@afsagag](https://huggingface.co/afsagag)