Update README.md

README.md

@@ -7,87 +7,124 @@ base_model:
 - AxionLab-official/MiniBot-0.9M-Base
 ---
 
-## 🧠 MiniBot-0.9M-Instruct
+# 🧠 MiniBot-0.9M-Instruct
 
-Instruction-tuned GPT-2 style language model (~900K parameters) optimized for Portuguese conversational tasks.
+> **Instruction-tuned GPT-2 style language model (~900K parameters) optimized for Portuguese conversational tasks.**
 
-## 📌 Model Overview
+[![Model](https://img.shields.io/badge/🤗%20Hugging%20Face-MiniBot--0.9M--Instruct-yellow)](https://huggingface.co/AxionLab-official/MiniBot-0.9M-Instruct)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Language](https://img.shields.io/badge/Language-Portuguese-blue)](https://huggingface.co/AxionLab-official/MiniBot-0.9M-Instruct)
+[![Parameters](https://img.shields.io/badge/Parameters-~900K-orange)](https://huggingface.co/AxionLab-official/MiniBot-0.9M-Instruct)
 
-MiniBot-0.9M-Instruct is an instruction-tuned version of MiniBot-0.9M-Base, designed to better follow prompts, respond to user inputs, and generate more coherent conversational outputs in Portuguese.
+---
+
+## 📌 Overview
+
+**MiniBot-0.9M-Instruct** is the instruction-tuned version of [MiniBot-0.9M-Base](https://huggingface.co/AxionLab-official/MiniBot-0.9M-Base), designed to follow prompts more accurately, respond to user inputs, and generate more coherent conversational outputs in **Portuguese**.
 
 Built on a GPT-2 architecture (~0.9M parameters), this model was fine-tuned on conversational and instruction-style data to improve usability in real-world interactions.
 
-🎯 Key Characteristics
-🇧🇷 Language: Portuguese (primary)
-🧠 Architecture: GPT-2 style (decoder-only Transformer)
-🔤 Embeddings: GPT-2 compatible
-📉 Parameters: ~900K
-⚙️ Base Model: MiniBot-0.9M-Base
-🎯 Fine-tuning: Instruction tuning (supervised)
-✅ Alignment: Basic prompt-following behavior
-🧠 What Changed from Base?
+---
+
+## 🎯 Key Characteristics
+
+| Attribute | Detail |
+|---|---|
+| 🇧🇷 **Language** | Portuguese (primary) |
+| 🧠 **Architecture** | GPT-2 style (Transformer decoder-only) |
+| 🔤 **Embeddings** | GPT-2 compatible |
+| 📉 **Parameters** | ~900K |
+| ⚙️ **Base Model** | MiniBot-0.9M-Base |
+| 🎯 **Fine-tuning** | Instruction tuning (supervised) |
+| ✅ **Alignment** | Basic prompt-following behavior |
+
+---
+
+## 🧠 What Changed from Base?
+
+Instruction tuning introduced significant behavioral improvements with no architectural changes:
+
+| Feature | Base | Instruct |
+|---|---|---|
+| Prompt understanding | ❌ | ✅ |
+| Conversational flow | ⚠️ Partial | ✅ |
+| Instruction following | ❌ | ✅ |
+| Overall coherence | Low | Improved |
+| Practical usability | Experimental | Functional |
 
-Compared to the base model:
+> 💡 The model is now significantly more usable in chat scenarios.
 
-Feature	Base	Instruct
-Prompt understanding	❌	✅
-Conversational flow	⚠️	✅
-Instruction following	❌	✅
-Coherence	Baixa	Melhorada
-Usability	Experimental	Practical
+---
+
+## 🏗️ Architecture
+
+The core architecture remains identical to the base model:
 
-👉 The model is now significantly more usable in chat scenarios.
+- **Decoder-only Transformer** (GPT-2 style)
+- Token embeddings + positional embeddings
+- Self-attention + MLP blocks
+- Autoregressive generation
 
-🏗️ Architecture
+No structural changes were made — only behavioral improvement through fine-tuning.
 
-Same core as base:
+---
 
-Decoder-only Transformer (GPT-2 style)
-Token + positional embeddings
-Self-attention + MLP blocks
-Autoregressive generation
+## 📚 Fine-Tuning Dataset
 
-No architectural changes — only behavioral improvement via fine-tuning.
+The model was fine-tuned on a Portuguese instruction-style conversational dataset composed of:
 
-📚 Fine-Tuning
-Dataset
+- 💬 Questions and answers
+- 📋 Simple instructions
+- 🤖 Assistant-style chat
+- 🎭 Basic roleplay
+- 🗣️ Natural conversations
 
-The model was fine-tuned on a Portuguese instruction-style conversational dataset, including:
+**Expected format:**
 
-Perguntas e respostas
-Instruções simples
-Chat estilo assistente
-Roleplay básico
-Conversas naturais
-Format
+```
 User: Me explique o que é gravidade
 Bot: A gravidade é a força que atrai objetos com massa...
-Strategy
-Supervised fine-tuning (SFT)
-Pattern learning for instruction-following
-No RLHF or preference optimization
-💡 Capabilities
+```
 
-✅ Strengths:
+**Training strategy:**
+- Supervised Fine-Tuning (SFT)
+- Pattern learning for instruction-following
+- No RLHF or preference optimization
 
-Seguir instruções simples
-Responder perguntas básicas
-Conversar de forma mais natural
-Melhor coerência em respostas curtas
-Estrutura de diálogo mais consistente
+---
+
+## 💡 Capabilities
+
+### ✅ Strengths
 
-❌ Limitations:
+- Following simple instructions
+- Answering basic questions
+- Conversing more naturally
+- Higher coherence in short responses
+- More consistent dialogue structure
 
-Raciocínio ainda limitado
-Pode errar fatos
-Não mantém contexto longo
-Sensível a prompts mal estruturados
+### ❌ Limitations
 
-👉 Mesmo com instruct tuning, ainda é um modelo extremamente pequeno.
+- Reasoning is still limited
+- May generate incorrect facts
+- Does not retain long context
+- Sensitive to poorly structured prompts
 
-🚀 Usage
-Hugging Face Transformers
-```Python
+> ⚠️ Even with instruction tuning, this remains an extremely small model. Adjust expectations accordingly.
+
+---
+
+## 🚀 Getting Started
+
+### Installation
+
+```bash
+pip install transformers torch
+```
+
+### Usage with Hugging Face Transformers
+
+```python
 from transformers import AutoTokenizer, AutoModelForCausalLM
 
 model_name = "AxionLab-official/MiniBot-0.9M-Instruct"
@@ -103,47 +140,69 @@ outputs = model.generate(
     max_new_tokens=80,
     temperature=0.7,
     top_p=0.9,
-    do_sample=True
+    do_sample=True,
 )
 
 print(tokenizer.decode(outputs[0], skip_special_tokens=True))
 ```
 
-⚙️ Recommended Settings
+### ⚙️ Recommended Settings
 
-Para melhor qualidade:
+| Parameter | Recommended Value | Description |
+|---|---|---|
+| `temperature` | `0.6 – 0.8` | Controls randomness |
+| `top_p` | `0.85 – 0.95` | Nucleus sampling |
+| `do_sample` | `True` | Enable sampling |
+| `max_new_tokens` | `40 – 100` | Response length |
 
-temperature: 0.6 – 0.8
-top_p: 0.85 – 0.95
-do_sample: True
-max_new_tokens: 40 – 100
+> 💡 Instruct models tend to perform better at lower temperatures. Try values around `0.65` for more accurate and focused responses.
 
-👉 Instruct models tendem a performar melhor com menos aleatoriedade.
+---
+
+## 🧪 Intended Use Cases
 
-🧪 Intended Use
-💬 Chatbots leves em português
-🎮 NPCs e jogos
-🧠 Testes de fine-tuning
-📚 Educação em NLP
-⚡ Aplicações locais (CPU-only)
-⚠️ Limitations
+| Use Case | Suitability |
+|---|---|
+| 💬 Lightweight Portuguese chatbots | ✅ Ideal |
+| 🎮 NPCs and games | ✅ Ideal |
+| 🧠 Fine-tuning experiments | ✅ Ideal |
+| 📚 NLP education | ✅ Ideal |
+| ⚡ Local / CPU-only applications | ✅ Ideal |
+| 🏭 Critical production environments | ❌ Not recommended |
 
-Modelo extremamente pequeno
-Sem alinhamento robusto
-Pode gerar respostas incorretas
-Não adequado para produção crítica
+---
 
-🔮 Future Work
-🧠 Reasoning-tuned version (MiniBot-Reason)
-📈 Scaling para 1M–10M parâmetros
-📚 Dataset mais diverso
-🤖 Melhor alinhamento de respostas
-🧩 Tool-use experiments
+## ⚠️ Disclaimer
 
-📜 License
+- Extremely small model (~900K parameters)
+- No robust alignment (no RLHF)
+- May generate incorrect or nonsensical responses
+- **Not suitable for critical production environments**
+
+---
 
-MIT
+## 🔮 Future Work
 
-👤 Author
+- [ ] 🧠 Reasoning-tuned version (`MiniBot-Reason`)
+- [ ] 📈 Scaling to 1M–10M parameters
+- [ ] 📚 Larger and more diverse dataset
+- [ ] 🤖 Improved response alignment
+- [ ] 🧩 Tool-use experiments
+
+---
+
+## 📜 License
+
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more details.
+
+---
+
+## 👤 Author
+
+Developed by **[AxionLab](https://huggingface.co/AxionLab-official)** 🔬
+
+---
 
-Developed by AxionLab
+<div align="center">
+  <sub>MiniBot-0.9M-Instruct · AxionLab · MIT License</sub>
+</div>