Update README.md

README.md

@@ -10,7 +10,6 @@ tags:
 - llama.cpp
 - ollama
 - local-llm
-- Neutrino
 pipeline_tag: text-generation
 datasets:
 - HuggingFaceFW/finepdfs
@@ -20,117 +19,231 @@ datasets:
 - codeparrot/github-code
 - HuggingFaceFW/finewiki
 - karpathy/fineweb-edu-100b-shuffle
-metrics:
-- accuracy
-- bertscore
-- bleu
-- bleurt
-- brier_score
-- cer
-library_name: transformers
+library_name: gguf
 base_model:
-- neuralcrew/neutrino-instruct
+- neuralcrew/neutrino
 ---
 
-# 🧠 Neutrino-Instruct (7B)
-![Alt text](https://ollama.com/assets/fardeen0424/neutrino/742305f0-8c9e-4ae8-acff-a7c2b133d3d8)
-Neutrino-Instruct is a **7B parameter instruction-tuned LLM** developed by **Fardeen NB**.  
-It is designed for **conversational AI**, **multi-step reasoning**, and **instruction-following** tasks, fine-tuned to maintain coherent and contextual dialogue across multiple turns.  
+<div align="center" style="text-align: center;">
 
-## ✨ Model Details
+# Neutrino-Instruct
 
-- **Model Name:** Neutrino-Instruct  
-- **Developer:** Fardeen NB  
-- **License:** Apache-2.0  
-- **Language(s):** English  
-- **Format:** GGUF (optimized for `llama.cpp` and `Ollama`)  
-- **Base Model:** Neutrino  
-- **Version:** 2.0  
-- **Task:** Text Generation (chat, Q&A, instruction-following)  
+![Neutrino](https://ollama.com/assets/fardeen0424/neutrino/742305f0-8c9e-4ae8-acff-a7c2b133d3d8)
 
-## 🚀 Quick Start
+**A 7B-parameter instruction-tuned language model for conversational AI**
 
-### Run with [llama.cpp](https://github.com/ggerganov/llama.cpp)
+<p align="center">
+<a href="#model-card">Model card</a> · <a href="#quickstart">Quickstart</a> · <a href="#architecture">Architecture</a> · <a href="#limitations--risks">Limitations</a> · <a href="#license">License</a>
+</p>
+
+</div>
+
+---
+
+## Model Card
+
+| Field | Value |
+|---|---|
+| **Developer** | Fardeen NB |
+| **Model type** | Autoregressive transformer, decoder-only |
+| **Parameters** | 7B |
+| **Base model** | [neuralcrew/neutrino](https://huggingface.co/neuralcrew/neutrino) |
+| **Fine-tuning** | Instruction tuning for multi-turn dialogue |
+| **Language(s)** | English |
+| **Format** | GGUF (quantized for `llama.cpp`, `Ollama`, `llama-cpp-python`) |
+| **License** | Apache 2.0 |
+| **Version** | 2.0 |
+
+---
+
+## Overview
+
+Neutrino-Instruct is a 7B-parameter language model fine-tuned from the Neutrino base model for conversational and instruction-following tasks. It is distributed in GGUF format for efficient local inference on consumer hardware via `llama.cpp`, `Ollama`, and `llama-cpp-python`.
+
+The model is designed to hold coherent, contextual dialogue across multiple turns and to follow natural-language instructions reliably at chat scale, while remaining light enough to run on a single consumer GPU or CPU-only machine.
+
+---
+
+## Intended Use
+
+**Primary use cases**
+- Conversational assistants and chatbots
+- Instruction-following agents (task completion, Q&A, summarization)
+- Local/offline research prototypes where data cannot leave the device
+- Educational and hobbyist LLM experimentation
+
+**Out of scope**
+- Medical, legal, or financial advice, or any use where model error could cause real-world harm
+- Autonomous decision-making without human review
+- Generation of content intended to deceive, impersonate, or manipulate
+- High-stakes classification (e.g., hiring, credit, law enforcement)
+
+Neutrino-Instruct is a general-purpose research and hobbyist model. It has **not** been evaluated for production or safety-critical deployment, and Fardeen NB makes no warranty as to its factual accuracy, safety, or fitness for any particular purpose.
+
+---
+
+## Quickstart
+
+### llama.cpp
 
 ```bash
-# Clone and build llama.cpp
 git clone https://github.com/ggerganov/llama.cpp
 cd llama.cpp && make
 
-# Run a single prompt
+# Single prompt
 ./main -m ./neutrino-instruct.gguf -p "Hello, who are you?"
 
-# Run in interactive mode
+# Interactive chat
 ./main -m ./neutrino-instruct.gguf -i -p "Let's chat."
 
 # Control output length
 ./main -m ./neutrino-instruct.gguf -n 256 -p "Write a poem about stars."
 
-# Change creativity (temperature)
+# Adjust temperature
 ./main -m ./neutrino-instruct.gguf --temp 0.7 -p "Explain quantum computing simply."
 
-# Enable GPU acceleration (if compiled with CUDA/Metal)
+# GPU offload (if built with CUDA/Metal)
 ./main -m ./neutrino-instruct.gguf --gpu-layers 50 -p "Summarize this article."
 ```
 
-### Run with [Ollama](https://ollama.com/fardeen0424/neutrino)
+### Ollama
 
 ```bash
 ollama run fardeen0424/neutrino
 ```
 
-### Run in Python (`llama-cpp-python`)
+### Python (llama-cpp-python)
 
 ```python
 from llama_cpp import Llama
 
-# Load the Neutrino-Instruct model
 llm = Llama(model_path="./neutrino-instruct.gguf")
 
-# Run inference
 response = llm("Who are you?")
 print(response["choices"][0]["text"])
 
-# Stream output tokens
+# Streaming
 for token in llm("Tell me a story about Neutrino:", stream=True):
     print(token["choices"][0]["text"], end="", flush=True)
 ```
 
-## 📊 System Requirements
+---
+
+## Training Data
+
+Neutrino-Instruct's base model was pretrained on a mixture of web, encyclopedic, code, and long-document text, and instruction-tuned on conversational data. Component sources include:
+
+| Dataset | Type | Role |
+|---|---|---|
+| finepdfs | Long-form documents | Pretraining |
+| finewiki | Encyclopedic text | Pretraining |
+| fineweb-edu-100b-shuffle | Educational web text | Pretraining |
+| wikipedia | Encyclopedic text | Pretraining |
+| github-code | Source code | Pretraining |
+| TinyStories | Short narrative text | Fine-tuning / eval |
+| awesome-chatgpt-prompts | Instruction/persona prompts | Instruction tuning |
+
+*Full dataset links are available in the metadata panel on the right side of this page.*
+
+### Training procedure
+
+| Field | Value |
+|---|---|
+| **Context length** | 32,768 tokens |
+| **Precision** | bfloat16 |
 
-* **CPU-only:** 32–64GB RAM recommended (runs on modern laptops, slower inference).
-* **GPU acceleration:**
+---
+
+## Architecture
+
+Neutrino-Instruct is built on a standard decoder-only Transformer stack. The core computations are as follows.
+
+**Scaled dot-product self-attention**, applied per head:
+
+$$\text{Attention}(Q, K, V) = \text{softmax}\!\left(\frac{QK^\top}{\sqrt{d_k}}\right)V$$
+
+with multi-head attention combining $h$ heads via a learned output projection:
+
+$$\text{MultiHead}(Q,K,V) = \text{Concat}(\text{head}_1, \dots, \text{head}_h)\,W^O, \qquad \text{head}_i = \text{Attention}(QW_i^Q, KW_i^K, VW_i^V)$$
 
-  * 4GB VRAM → 4-bit quantized (Q4) models
-  * 8GB VRAM → 5-bit/8-bit models
-  * 12GB+ VRAM → FP16 full precision
+Neutrino-Instruct uses **grouped-query attention (GQA)**: the 32 query heads are partitioned into $g=8$ groups, each group sharing a single key/value projection ($KW^K_g, VW^V_g$) instead of every query head having its own — trading a small amount of expressivity for a much smaller KV cache at inference time.
 
+**Position encoding** — rotary position embeddings (RoPE), applied to query/key vectors by rotating consecutive coordinate pairs as a function of token position $m$ and frequency $\theta_i$:
 
-## 🧩 Potential Use Cases
+$$f(x_m, m) = \big[x_m^{(1)}\cos m\theta_i - x_m^{(2)}\sin m\theta_i,\ \ x_m^{(1)}\sin m\theta_i + x_m^{(2)}\cos m\theta_i\big]$$
 
-* Conversational AI assistants
-* Research prototypes
-* Instruction-following agents
-* Chatbots with identity-awareness
+**Feed-forward block** (SwiGLU-style gating):
 
-⚠️ **Out of Scope:** Use in critical decision-making, legal, or medical contexts.
+$$\text{FFN}(x) = \big(\text{Swish}(xW_1)\otimes xW_3\big)W_2$$
 
-## 🛠️ Development Notes
+**Pre-normalization** (RMSNorm) around each sub-block:
 
-* Model uploaded in **GGUF format** for portability & performance.
-* Compatible with **llama.cpp**, **Ollama**, and **llama-cpp-python**.
-* Supports quantization levels (Q4, Q5, Q8) for deployment on resource-constrained devices.
+$$\text{RMSNorm}(x) = \frac{x}{\sqrt{\frac{1}{n}\sum_{i=1}^n x_i^2 + \epsilon}} \odot g$$
 
-## 📖 Citation
+**Training objective** — standard next-token cross-entropy over the vocabulary:
 
-If you use Neutrino in your research or projects, please cite:
+$$\mathcal{L} = -\sum_{t=1}^{T} \log P_\theta(x_t \mid x_{<t})$$
+
+| Hyperparameter | Value |
+|---|---|
+| Layers | 32 |
+| Hidden size | 4096 |
+| Intermediate (FFN) size | 14336 |
+| Attention heads | 32 |
+| KV heads (GQA) | 8 |
+| Vocabulary size | 32,768 |
+| Max context length | 32,768 |
+| Activation | SiLU (SwiGLU gating) |
+| Normalization | RMSNorm (pre-norm, $\epsilon=1\text{e-}5$) |
+| Position encoding | RoPE ($\theta=1{,}000{,}000$) |
+| Sliding window | None (full attention) |
+| Precision | bfloat16 |
+| Tied embeddings | No |
+
+---
+
+## Quantization & System Requirements
+
+| Setup | VRAM / RAM | Recommended quantization |
+|---|---|---|
+| CPU-only | 32–64 GB RAM | Q4_K_M / Q5_K_M |
+| GPU (entry) | 4 GB VRAM | Q4 |
+| GPU (mid) | 8 GB VRAM | Q5 / Q8 |
+| GPU (high) | 12 GB+ VRAM | FP16 (full precision) |
+
+---
+
+## Limitations & Risks
+
+- **Hallucination**: Like all LLMs, Neutrino-Instruct can generate plausible-sounding but incorrect or fabricated information. Outputs should be verified before use in any consequential context.
+- **Bias**: Training data drawn from web and code sources may encode social, cultural, or representational biases present in that data. The model has not undergone a formal bias audit.
+- **Safety tuning**: No dedicated safety alignment (red-teaming, RLHF/DPO refusal training, etc.) has been performed beyond the base instruction tuning. The model may comply with harmful, unsafe, or policy-violating requests.
+- **Language coverage**: English only; behavior on other languages is unevaluated and likely degraded.
+- **Context length**: Supports up to 32,768 tokens; quality may degrade toward the upper end of that window, as is typical for RoPE-based models — this has not been separately verified for Neutrino-Instruct.
+- **No factual grounding**: The model has no live access to external tools, retrieval, or the internet; all knowledge is frozen at training time.
+
+This model has not been evaluated by a third party or independent safety team. Users deploying it in any user-facing product are responsible for their own safety evaluation, content filtering, and monitoring.
+
+---
+
+## License
+
+Released under the **Apache License 2.0**. See [LICENSE](https://www.apache.org/licenses/LICENSE-2.0) for full terms.
+
+---
+
+## Citation
 
 ```bibtex
 @misc{fardeennb2025neutrino,
-  title = {Neutrino-Instruct: A 7B Instruction-Tuned Conversational Model},
-  author = {Fardeen NB},
-  year = {2025},
+  title        = {Neutrino-Instruct: A 7B Instruction-Tuned Conversational Model},
+  author       = {Fardeen NB},
+  year         = {2025},
   howpublished = {Hugging Face},
-  url = {https://huggingface.co/neuralcrew/neutrino-instruct}
+  url          = {https://huggingface.co/neuralcrew/neutrino-instruct}
 }
-```
+```
+
+## Acknowledgements
+
+Built on top of the Neutrino base model. Thanks to the maintainers of the open datasets listed above, and to the `llama.cpp`, `Ollama`, and `llama-cpp-python` projects for inference tooling.