Update README.md

README.md

@@ -24,157 +24,85 @@ quantization:
   bnb_4bit_compute_dtype: float16
   bnb_4bit_use_double_quant: true
 ---
+
 # Model Card for llama_poetry_fa
 
 **Model Name:** llama_poetry_fa  
-**Model URL:** https://huggingface.co/8lianno/llama_poetry_fa
+**Model URL:** [https://huggingface.co/8lianno/llama_poetry_fa](https://huggingface.co/8lianno/llama_poetry_fa)
 
-This model is trained on a Llama 3.1-based checkpoint, focusing on generating Persian poetry. It returns responses in Persian poetic form, incorporating suitable rhyme and rhythm based on the given prompt.
+## Model Summary
 
-{{ model_summary | default("", true) }}
+`llama_poetry_fa` is a Persian poetry generation model fine-tuned from a Llama 3.1-based checkpoint. It aims to produce stylistically coherent, culturally relevant, and metrically sound verses in response to a user’s prompt. The model focuses on generating output that aligns with classical Persian poetic traditions, such as maintaining consistent rhyme schemes and thematic unity.
 
 ## Model Details
 
 ### Model Description
 
-{{ model_description | default("", true) }}
+- **Developed by:** 8lianno  
+- **Model type:** Causal Language Model (Llama-based, instruction-tuned)  
+- **Language:** Persian (fa)  
+- **License:** *[More Information Needed]*  
+- **Finetuned from:** `meta-llama/Llama-3.1-8B-Instruct`
 
-- **Developed by:** {{ developers | default("[More Information Needed]", true)}}
-- **Funded by [optional]:** {{ funded_by | default("[More Information Needed]", true)}}
-- **Shared by [optional]:** {{ shared_by | default("[More Information Needed]", true)}}
-- **Model type:** {{ model_type | default("Causal Language Model (Llama-based)", true)}}
-- **Language(s) (NLP):** {{ language | default("fa", true)}}
-- **License:** {{ license | default("[More Information Needed]", true)}}
-- **Finetuned from model [optional]:** {{ base_model | default("meta-llama/Llama-3.1-8B-Instruct", true)}}
+This model has been trained to understand Persian poetic structure, using additional tokens `[شروع_شعر]`, `[پایان_شعر]`, and `[مصرع]` to guide and maintain poem formatting. It can respond to various thematic prompts—whether about nature, love, historical figures, or abstract concepts—and produce a poem that attempts to follow Persian poetry norms.
 
-### Model Sources [optional]
+### Model Sources
 
-- **Repository:** {{ repo | default("https://huggingface.co/8lianno/llama_poetry_fa", true)}}
-- **Paper [optional]:** {{ paper | default("[More Information Needed]", true)}}
-- **Demo [optional]:** {{ demo | default("[More Information Needed]", true)}}
+- **Repository:** [https://huggingface.co/8lianno/llama_poetry_fa](https://huggingface.co/8lianno/llama_poetry_fa)  
+- **Paper [optional]:** No formal paper at this time.  
+- **Demo [optional]:** Future demonstration pages may be provided.
 
 ## Uses
 
 ### Direct Use
 
-{{ direct_use | default("Intended for generating Persian poems in response to user queries.", true)}}
+This model is intended to generate Persian poetry in response to user prompts. It can be used as a creative writing aid, a tool for literary exploration, or as a source of inspiration for authors, poets, and students studying Persian literature.
+
+**Example:**
+- **Prompt:** "درباره بهار شعری بسرایید"  
+- **Response:** A poem about spring, attempting to maintain poetic structure and rhyme.
 
-### Downstream Use [optional]
+### Downstream Use
 
-{{ downstream_use | default("[More Information Needed]", true)}}
+While primarily designed for poetry generation, the model can be integrated into:
+- Persian literature chatbots
+- Educational applications for Persian poetry studies
+- Cultural or literary heritage projects
 
 ### Out-of-Scope Use
 
-{{ out_of_scope_use | default("Not suitable for factual QA tasks, non-Persian text generation, or high-stakes decision making.", true)}}
+The model is not designed for:
+- Factual Question-Answering (it may produce poetic but factually incorrect answers)
+- Non-Persian text generation
+- High-stakes decision making
 
 ## Bias, Risks, and Limitations
 
-{{ bias_risks_limitations | default("The model may produce culturally specific or biased content and may not reflect all poetic traditions accurately.", true)}}
+The model’s content is drawn from its training data and may reflect certain cultural or poetic biases. It might:
+- Present thematically repetitive motifs or styles from classical Persian poetry.
+- Struggle with modern or colloquial Persian forms.
+- Occasionally produce incoherent or repetitive verses.
+
+Users should critically evaluate the generated text, especially if used in academic or public-facing contexts.
 
 ### Recommendations
 
-{{ bias_recommendations | default("Users should review generated poems critically for cultural biases or inappropriate content before use.", true)}}
+- Review generated poems for cultural appropriateness.
+- Verify factual accuracy independently.
+- For sensitive or controversial topics, consider human moderation.
 
 ## How to Get Started with the Model
 
-{{ get_started_code | default("See the included poetry_generator.py for an example of loading and generating poems.", true)}}
-
-## Training Details
-
-### Training Data
-
-{{ training_data | default("The model was trained on a collection of Persian poetry and literature. More details needed.", true)}}
-
-### Training Procedure
-
-#### Preprocessing [optional]
-
-{{ preprocessing | default("[More Information Needed]", true)}}
-
-#### Training Hyperparameters
-
-- **Training regime:** {{ training_regime | default("Fine-tuned with LoRA and 4-bit quantization.", true)}}
-
-#### Speeds, Sizes, Times [optional]
-
-{{ speeds_sizes_times | default("[More Information Needed]", true)}}
-
-## Evaluation
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-{{ testing_data | default("Internal Persian poetry test samples.", true)}}
-
-#### Factors
-
-{{ testing_factors | default("[More Information Needed]", true)}}
-
-#### Metrics
-
-{{ testing_metrics | default("[More Information Needed]", true)}}
-
-### Results
-
-{{ results | default("[More Information Needed]", true)}}
-
-#### Summary
-
-{{ results_summary | default("", true) }}
-
-## Model Examination [optional]
-
-{{ model_examination | default("[More Information Needed]", true)}}
-
-## Environmental Impact
-
-- **Hardware Type:** {{ hardware_type | default("[More Information Needed]", true)}}
-- **Hours used:** {{ hours_used | default("[More Information Needed]", true)}}
-- **Cloud Provider:** {{ cloud_provider | default("[More Information Needed]", true)}}
-- **Compute Region:** {{ cloud_region | default("[More Information Needed]", true)}}
-- **Carbon Emitted:** {{ co2_emitted | default("[More Information Needed]", true)}}
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-{{ model_specs | default("Llama-based causal language model fine-tuned for Persian poetry.", true)}}
-
-### Compute Infrastructure
-
-{{ compute_infrastructure | default("[More Information Needed]", true)}}
-
-#### Hardware
-
-{{ hardware_requirements | default("[More Information Needed]", true)}}
-
-#### Software
-
-{{ software | default("[More Information Needed]", true)}}
-
-## Citation [optional]
-
-**BibTeX:**
-
-{{ citation_bibtex | default("[More Information Needed]", true)}}
-
-**APA:**
-
-{{ citation_apa | default("[More Information Needed]", true)}}
-
-## Glossary [optional]
-
-{{ glossary | default("[More Information Needed]", true)}}
-
-## More Information [optional]
-
-{{ more_information | default("[More Information Needed]", true)}}
-
-## Model Card Authors [optional]
+Use the provided `poetry_generator.py` script:
 
-{{ model_card_authors | default("[More Information Needed]", true)}}
+```python
+from poetry_generator import PoetryGenerator
 
-## Model Card Contact
+generator = PoetryGenerator(
+    model_path="/path/to/your/trained/model",
+    token="your_hf_token"
+)
 
-{{ model_card_contact | default("[More Information Needed]", true)}}
+prompt = "امید چیست؟"
+poem = generator.generate_poem(prompt)
+print(poem)