Update README.md

README.md

@@ -1,199 +1,311 @@
 ---
 library_name: transformers
-tags: []
+base_model:
+- google/gemma-3-270m-it
+tags:
+- text-generation
+- character-generation
+- creative-writing
+- peft
+- lora
+- gemma
+- storytelling
+language:
+- en
+license: apache-2.0
+datasets:
+- NousResearch/CharacterCodex
+pipeline_tag: text-generation
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
-
+# Gemma 270M Character Generator
 
+A fine-tuned version of Google's Gemma 3 270M instruction-tuned model, specialized in generating creative character descriptions for storytelling and creative writing projects.
 
 ## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
+This model generates unique character names and descriptions based on story genre and setting. It has been fine-tuned using LoRA (Low-Rank Adaptation) on the CharacterCodex dataset, making it capable of creating diverse characters across various genres including Fantasy, Sci-Fi, Horror, Manga, Cyberpunk, and more.
 
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+The model takes a genre and setting as input and produces a character name followed by a detailed description including physical appearance, personality traits, and unique characteristics.
 
-- **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]
+- **Developed by:** [Your Name/Organization]
+- **Model type:** Causal Language Model (Text Generation)
+- **Language(s):** English
+- **License:** Apache 2.0
+- **Finetuned from model:** google/gemma-3-270m-it
 
-### Model Sources [optional]
+### Model Sources
 
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+- **Base Model:** [google/gemma-3-270m-it](https://huggingface.co/google/gemma-3-270m-it)
+- **Dataset:** [NousResearch/CharacterCodex](https://huggingface.co/datasets/NousResearch/CharacterCodex)
 
 ## 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]
+This model is designed for:
+- **Creative writers** generating characters for stories, novels, or screenplays
+- **Game developers** creating NPCs and character concepts
+- **Dungeon Masters** generating characters for tabletop RPGs
+- **Content creators** needing character ideas for various media
+- **Writing prompts** and creative inspiration
+
+### Example Usage
+
+```python
+import torch
+from transformers import AutoTokenizer, AutoModelForCausalLM
+from peft import PeftModel
+
+# Load base model
+base_model = AutoModelForCausalLM.from_pretrained(
+    "google/gemma-3-270m-it",
+    torch_dtype=torch.bfloat16,
+    device_map="auto"
+)
+
+# Load fine-tuned LoRA adapters
+model = PeftModel.from_pretrained(base_model, "your-username/gemma-character-generator")
+tokenizer = AutoTokenizer.from_pretrained("your-username/gemma-character-generator")
+
+# Generate a character
+messages = [{
+    "role": "user",
+    "content": "Create a character for a Fantasy story. Setting: A mystical forest inhabited by ancient spirits"
+}]
+
+prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+
+outputs = model.generate(
+    **inputs,
+    max_new_tokens=256,
+    temperature=0.7,
+    top_p=0.9,
+    repetition_penalty=1.2,
+    do_sample=True
+)
+
+character = tokenizer.decode(outputs[0][inputs['input_ids'].shape[-1]:], skip_special_tokens=True)
+print(character)
+```
+
+### Example Output
+
+**Input:**
+- Genre: Fantasy
+- Setting: A mystical forest inhabited by ancient spirits
+
+**Output:**
+```
+Elara Moonshadow
+
+A half-elf druid with silver hair that flows like moonlight and emerald eyes that glow faintly in the darkness. She wears robes woven from living vines and moss, adorned with crystals that pulse with ancient magic. Elara can communicate with the forest spirits and carries a staff carved from the heartwood of a thousand-year-old oak. Her presence brings calm to troubled souls, though she harbors a deep sorrow from a past betrayal.
+```
 
 ### 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 **not suitable for**:
+- Generating real person descriptions or impersonating real individuals
+- Creating harmful, offensive, or discriminatory character stereotypes
+- Medical, legal, or financial advice through character personas
+- Generating characters for misleading or malicious purposes
 
 ## Bias, Risks, and Limitations
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
+- The model may reflect biases present in the training data (CharacterCodex dataset)
+- Generated characters may sometimes include stereotypical traits based on genre conventions
+- The model works best with genres well-represented in the training data (Fantasy, Sci-Fi, Horror)
+- May generate repetitive descriptions if temperature is set too low
+- Limited to character descriptions; does not generate character stats, abilities, or game mechanics
 
 ### 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]
+- Review and edit generated content to ensure it aligns with your creative vision
+- Adjust generation parameters (temperature, top_p, repetition_penalty) for varied outputs
+- Use the model as a creative starting point rather than final output
+- Be mindful of cultural sensitivity when using generated characters
+- Test with different prompts if initial results don't meet expectations
 
 ## 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. -->
+The model was fine-tuned on a filtered subset of the [CharacterCodex dataset](https://huggingface.co/datasets/NousResearch/CharacterCodex), containing approximately 3,000 character entries from various media sources including:
+- Fantasy novels and games
+- Sci-Fi literature
+- Manga and anime
+- Horror fiction
+- Video games
+- Tabletop RPGs
 
-[More Information Needed]
+Only entries from media sources with more than 10 samples were included to ensure quality and diversity.
 
 ### 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]
+#### Fine-tuning Method
 
-[More Information Needed]
+**LoRA (Low-Rank Adaptation)** was used to efficiently fine-tune the model:
+- Only ~1.5% of model parameters were trained
+- Adapter layers applied to attention and MLP modules
+- Preserves base model knowledge while specializing for character generation
 
+#### Data Formatting
 
-#### 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 -->
+Training examples were formatted as conversational turns:
+```
+User: Create a character for a [GENRE] story. Setting: [SETTING]
+Assistant: [CHARACTER_NAME]
 
-#### Speeds, Sizes, Times [optional]
+[CHARACTER_DESCRIPTION]
+```
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+#### Training Hyperparameters
 
-[More Information Needed]
+- **Base Model:** google/gemma-3-270m-it (270M parameters)
+- **Training Method:** LoRA (Low-Rank Adaptation)
+- **LoRA Rank (r):** 8
+- **LoRA Alpha:** 32
+- **LoRA Dropout:** 0.05
+- **Target Modules:** q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
+- **Learning Rate:** 5e-5
+- **Optimizer:** AdamW (8-bit)
+- **Learning Rate Scheduler:** Cosine
+- **Warmup Ratio:** 0.1
+- **Training Epochs:** 3
+- **Batch Size per Device:** 4
+- **Gradient Accumulation Steps:** 4
+- **Effective Batch Size:** 16
+- **Max Sequence Length:** 512 tokens
+- **Training Precision:** bfloat16
+- **Training Framework:** TRL (Transformers Reinforcement Learning)
+
+#### Training Hardware
+
+- **GPU:** NVIDIA T4 / A100 (Google Colab)
+- **Training Time:** ~1-2 hours (3 epochs on 3,000 samples)
+- **GPU Memory Usage:** ~10-12 GB
 
 ## 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
+### Generation Quality
 
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+The model was evaluated through:
+1. **Manual inspection** of generated characters across different genres
+2. **Coherence testing** - ensuring character descriptions are logically consistent
+3. **Diversity testing** - verifying varied outputs with different temperature settings
+4. **Format adherence** - checking output follows expected structure (name + description)
 
-[More Information Needed]
+### Sample Generations
 
-#### Metrics
+**Genre: Sci-Fi**  
+**Setting:** A space station orbiting a dying star
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+```
+Commander Aria Vex
 
-[More Information Needed]
+A cybernetically enhanced human with chrome-plated neural implants visible along her temples. Her eyes have been replaced with advanced optical sensors that glow ice-blue in low light. She wears a patched Alliance military jacket over her station-issued jumpsuit, decorated with medals from the Outer Rim conflicts. Despite her harsh exterior, she carries deep guilt over the crew members lost under her command.
+```
 
-### Results
+**Genre: Horror**  
+**Setting:** An abandoned asylum with whispers in the walls
 
-[More Information Needed]
+```
+Dr. Elias Blackwood
 
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
+A gaunt psychiatrist with hollow cheeks and eyes that seem to have witnessed unspeakable horrors. His white coat is stained with substances best left unidentified, and he carries a leather journal filled with illegible notes written in trembling handwriting. He speaks in hushed tones and frequently glances over his shoulder, as if something is following him through the empty corridors.
+```
 
 ## 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:** NVIDIA T4 GPU (Google Colab)
+- **Hours used:** ~1.5 hours
+- **Cloud Provider:** Google Cloud Platform
+- **Compute Region:** US (variable)
+- **Carbon Emitted:** Minimal (~0.05 kg CO2eq estimated for training)
 
-- **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]
+Fine-tuning with LoRA significantly reduces computational requirements compared to full model training, resulting in lower environmental impact.
 
-## Technical Specifications [optional]
+## Technical Specifications
 
-### Model Architecture and Objective
+### Model Architecture
 
-[More Information Needed]
+- **Architecture:** Gemma (Decoder-only Transformer)
+- **Base Parameters:** 270M
+- **Trainable Parameters:** ~4M (LoRA adapters, 1.5% of total)
+- **Attention Heads:** 8
+- **Hidden Size:** 2048
+- **Layers:** 18
+- **Context Length:** 8192 tokens (base model capability)
+- **Vocabulary Size:** 256,000 tokens
 
 ### Compute Infrastructure
 
-[More Information Needed]
-
 #### Hardware
 
-[More Information Needed]
+- Training: Google Colab with NVIDIA T4/A100 GPU
+- Inference: Can run on consumer GPUs with 6GB+ VRAM
 
 #### Software
 
-[More Information Needed]
+- **Framework:** Transformers 4.46+
+- **Training Library:** TRL (Transformers Reinforcement Learning)
+- **PEFT Library:** PEFT 0.13+
+- **Python Version:** 3.10+
+- **PyTorch:** 2.0+
 
-## Citation [optional]
+## Citation
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+If you use this model in your work, please cite:
 
 **BibTeX:**
 
-[More Information Needed]
+```bibtex
+@misc{gemma-character-generator-2026,
+  author = {Your Name},
+  title = {Gemma 270M Character Generator: Fine-tuned Model for Creative Character Generation},
+  year = {2026},
+  publisher = {HuggingFace},
+  journal = {HuggingFace Model Hub},
+  howpublished = {\url{https://huggingface.co/your-username/gemma-character-generator}}
+}
+```
 
-**APA:**
+**Base Model Citation:**
 
-[More Information Needed]
+```bibtex
+@article{gemma_2024,
+  title={Gemma: Open Models Based on Gemini Research and Technology},
+  author={Gemma Team},
+  year={2024},
+  journal={Google DeepMind}
+}
+```
 
-## Glossary [optional]
+## Glossary
 
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+- **LoRA (Low-Rank Adaptation):** An efficient fine-tuning method that adds trainable low-rank matrices to model layers
+- **PEFT (Parameter-Efficient Fine-Tuning):** Techniques for fine-tuning large models with minimal parameter updates
+- **Temperature:** Controls randomness in generation; higher values (0.8-1.0) produce more creative/diverse outputs
+- **Top-p (Nucleus Sampling):** Samples from the smallest set of tokens whose cumulative probability exceeds p
+- **Repetition Penalty:** Discourages the model from repeating the same tokens/phrases
 
-[More Information Needed]
+## More Information
 
-## More Information [optional]
+### Generation Tips
 
-[More Information Needed]
+1. **For more creative characters:** Increase temperature to 0.8-0.9
+2. **For more focused characters:** Decrease temperature to 0.5-0.6
+3. **To prevent repetition:** Set repetition_penalty to 1.2-1.3
+4. **For longer descriptions:** Increase max_new_tokens to 384-512
+5. **For varied outputs:** Try different random seeds with torch.manual_seed()
 
-## Model Card Authors [optional]
+### Supported Genres
 
-[More Information Needed]
+Works well with: Fantasy, Sci-Fi, Horror, Cyberpunk, Steampunk, Manga, Anime, Mystery, Thriller, Post-Apocalyptic, Urban Fantasy, Space Opera
 
-## Model Card Contact
+## Model Card Authors
 
-[More Information Needed]
+[Pranshu Jain](https://www.linkedin.com/in/pranshu32)