Create README.md

README.md

@@ -0,0 +1,369 @@
+---
+license: apache-2.0
+---
+
+
+# Instinct-1B
+
+**[autonomousX/Instinct-1B on Hugging Face](https://huggingface.co/autonomousX)**
+
+**[Training scripts and Logs on GITHUB](https://github.com/YADAV1825/AutonomousX-Instinct)**
+
+*Instinct-1B is a fully reproducible, from-scratch trained 1B parameter language model trained on 85B tokens using TPU v4 infrastructure.*
+
+**Instinct-1B** is a 1B parameter Large Language Model built entirely from scratch under the **AutonomousX** organization. 
+
+Compute for this project was supported by **[Google's TRC Program (TPU Research Cloud)](https://sites.research.google/trc/about/)**.
+
+---
+
+### 👨‍💻 Author Information
+**Rohit Yadav** B.Tech 3rd Year  
+Dr. B.R. Ambedkar National Institute of Technology (NIT) Jalandhar, India  
+**E-mail:** [yrohit1825@gmail.com](mailto:yrohit1825@gmail.com)  
+**LinkedIn:** [Rohit Yadav](https://www.linkedin.com/in/rohit-yadav-25535b256/)  
+**GitHub:** [YADAV1825](https://github.com/YADAV1825)
+
+**Research interests include:** Large Language Models, MultiModal Pipelines, Systems Programming, AI Infrastructure, Distributed Training.
+
+---
+# About AutonomousX
+
+AutonomousX focuses on open-source contributions aimed at building Large Language Models from scratch using custom training pipelines. Our work explores different training configurations including optimizers, datasets, and scalable TPU training using JAX and pmap. The goal is to provide transparent and reproducible implementations so that researchers, students, and developers can understand how modern LLMs are trained end-to-end.
+
+Due to the current scarcity of complete beginner-friendly guides for training LLMs on TPUs, especially using JAX, AutonomousX aims to bridge this gap by publishing full training pipelines, scripts, and documentation for the open-source community.
+
+Maintained by: Rohit Yadav | B.Tech NIT Jalandhar | yrohit1825@gmail.com | [Hugging_Face](https://huggingface.co/autonomousX)
+
+---
+
+### ⚠️ Disclaimer
+**This is a base model, not an SFT (Supervised Fine-Tuned) or RLHF (Reinforcement Learning from Human Feedback) model.** As a raw completion model, it may output undesired, biased, or nonsensical text. It is intended primarily for research and educational purposes.
+
+---
+
+### 📊 Model Overview
+
+| Attribute | Value |
+| :--- | :--- |
+| **Model Name** | Instinct-1B |
+| **Organization** | AutonomousX |
+| **Parameters** | 1B |
+| **Vocabulary Size** | 50,304 |
+| **Dataset** | PILE |
+| **Tokenizer** | Pythia Tokenizer / BPE |
+| **Tokens Seen** | 85B |
+| **Training Hardware** | TPU v4-8 |
+| **Optimizer** | AdamW |
+| **Architecture** | v-4 (128) pmap |
+| **Positional Embeddings**| No RoPE |
+
+---
+
+### 🧠 Training Details
+
+Instinct-1B was trained completely **from scratch** using **JAX/Flax on TPU v4-8 hardware**. 
+
+The training pipeline includes:
+* Dataset streaming from **PILE**.
+* **Pythia Tokenizer** with a 50,304 vocabulary size.
+* TPU optimized **JAX / Flax** training loop.
+* **AdamW** optimizer for stable convergence.
+* Checkpointing and validation during training.
+* Rolling validation shard evaluation.
+
+#### 🔄 Training Workflow
+
+```mermaid
+graph TD
+    %% Dataset and Preparation
+    Data["Dataset: PILE\nRaw Text Data"]
+    Tokenizer["BPE Tokenizer\nVocabulary Construction"]
+    TokenizedData["Tokenized Data\nReady for Training"]
+
+    %% Model Architecture
+    Model["v-4 (128) pmap\nTransformer Decoder\n1B Parameters"]
+    RoPE["No RoPE Positional Embeddings"]
+
+    %% Training Pipeline
+    Optimizer["Optimizer: AdamW"]
+    ForwardPass["Forward Pass\nCompute Loss"]
+    BackwardPass["Backward Pass\nCompute Gradients"]
+    Update["Parameter Update"]
+
+    %% Logging and Checkpoints
+    Checkpoints["Model Checkpoints\nSaved up to 85B tokens"]
+    Logs["Training Logs\nLoss & Perplexity"]
+
+    %% Connections
+    Data --> Tokenizer
+    Tokenizer --> TokenizedData
+    TokenizedData --> ForwardPass
+    
+    Model --> ForwardPass
+    RoPE -.-> Model
+
+    ForwardPass --> BackwardPass
+    BackwardPass --> Optimizer
+    Optimizer --> Update
+    Update --> Model
+
+    Update --> Checkpoints
+    Update --> Logs
+```
+
+#### 📈 Training Curves
+The loss curves are saved in `training_log.txt` and `val_perplexity.txt`. Below is the visualization of the training progress:
+
+![image](https://cdn-uploads.huggingface.co/production/uploads/68bf07a31d80a360f1405b72/2B9ti99z5LZsY-SYeIeAk.png)
+
+---
+
+### 🔄 Reproducibility
+
+The entire pipeline used to train the model is fully reproducible. This includes the dataset pipeline, tokenizer creation, model architecture, TPU training loop, and checkpointing system.
+
+**Full training pipeline repository:** [train.py](https://github.com/YADAV1825/Instinct-1B/blob/main/train.py) (Example link format)
+
+---
+
+### 🚀 Run Inference (Colab TPU/GPU)
+
+The trained LLM inference script and model weights are available at: [autonomousX/Instinct-1B on Hugging Face](https://huggingface.co/autonomousX).
+
+⚠️ **Disclaimer:** *This is a sample inference script originally written for the 0.5B (40B) variants. Please adjust parameters like `N_LAYERS`, `D_MODEL`, `N_HEADS`, `D_HEAD`, `D_FF`, etc., according to this specific model's architecture (1B) to run inference successfully.*
+
+A ready-to-run Google Colab TPU/GPU inference script is provided below. Simply open a notebook, set your runtime to TPU or GPU, and run it. *(Please be patient, it may take around 20 mins to run the model initialization).*
+
+<details>
+<summary>Click here to view the full Inference Code</summary>
+
+```python
+#please be patient It may take 20 mins to run the model
+# Install huggingface_hub if not installed
+!pip install -q huggingface_hub
+
+from huggingface_hub import snapshot_download
+
+repo_id = "autonomousX/Instinct-1B"
+
+# Download entire repository
+local_path = snapshot_download(
+    repo_id=repo_id,
+    repo_type="model",
+    local_dir="TPU_1B",
+    local_dir_use_symlinks=False
+)
+
+print("Download complete!")
+print("Saved to:", local_path)
+
+# =========================
+# FAST 1B INFERENCE CELL
+# =========================
+
+import os
+import math
+import jax
+import jax.numpy as jnp
+from flax import linen as nn
+from flax.training import train_state, checkpoints
+import optax
+from transformers import AutoTokenizer
+
+# ---------------- CONFIG ----------------
+SEQ_LEN = 1024
+VOCAB_SIZE = 50304
+
+# NOTE: Adjust these parameters for your specific 1B architecture!
+N_LAYERS = 32
+D_MODEL = 1024
+N_HEADS = 16
+D_HEAD = 64
+D_FF = 4096
+ROTARY_PCT = 0.25
+
+CKPT_PATH = os.path.abspath("TPU_1B/checkpoint_0")
+
+# ---------------- RoPE ----------------
+def build_rope_cache(seq_len, head_dim, rotary_pct):
+    dim = int(head_dim * rotary_pct)
+    freqs = 1.0 / (10000 ** (jnp.arange(0, dim, 2) / dim))
+    pos = jnp.arange(seq_len)
+    angles = jnp.einsum("i,j->ij", pos, freqs)
+    return jnp.sin(angles), jnp.cos(angles)
+
+ROPE_SIN, ROPE_COS = build_rope_cache(SEQ_LEN, D_HEAD, ROTARY_PCT)
+
+def apply_rope(q, k):
+    dim = int(D_HEAD * ROTARY_PCT)
+    T = q.shape[1]
+
+    sin = ROPE_SIN[:T][None, :, None, :]
+    cos = ROPE_COS[:T][None, :, None, :]
+
+    q_rot, q_pass = q[..., :dim], q[..., dim:]
+    k_rot, k_pass = k[..., :dim], k[..., dim:]
+
+    q1, q2 = q_rot[..., ::2], q_rot[..., 1::2]
+    k1, k2 = k_rot[..., ::2], k_rot[..., 1::2]
+
+    q_rot = jnp.concatenate(
+        [q1 * cos - q2 * sin,
+         q1 * sin + q2 * cos],
+        axis=-1
+    )
+
+    k_rot = jnp.concatenate(
+        [k1 * cos - k2 * sin,
+         k1 * sin + k2 * cos],
+        axis=-1
+    )
+
+    return (
+        jnp.concatenate([q_rot, q_pass], axis=-1),
+        jnp.concatenate([k_rot, k_pass], axis=-1),
+    )
+
+# ---------------- MODEL ----------------
+class RMSNorm(nn.Module):
+    dim: int
+    eps: float = 1e-6
+    @nn.compact
+    def __call__(self, x):
+        scale = self.param("scale", nn.initializers.ones, (self.dim,))
+        norm = jnp.sqrt(jnp.mean(x**2, axis=-1, keepdims=True) + self.eps)
+        return x * (scale / norm)
+
+class Attention(nn.Module):
+    @nn.compact
+    def __call__(self, x, mask):
+        B, T, C = x.shape
+        qkv = nn.Dense(3 * C, use_bias=False, dtype=jnp.bfloat16)(x)
+        qkv = qkv.reshape(B, T, 3, N_HEADS, D_HEAD)
+
+        q = qkv[:, :, 0]
+        k = qkv[:, :, 1]
+        v = qkv[:, :, 2]
+
+        q, k = apply_rope(q, k)
+
+        att = jnp.einsum("bthd,bshd->bhts", q, k)
+        att = att / math.sqrt(D_HEAD)
+
+        mask = mask.astype(jnp.float32)
+        mask = (1.0 - mask) * -1e10
+        att = att + mask
+
+        att = nn.softmax(att.astype(jnp.float32), axis=-1)
+        att = att.astype(jnp.bfloat16)
+
+        out = jnp.einsum("bhts,bshd->bthd", att, v)
+        out = out.reshape(B, T, C)
+
+        return nn.Dense(C, use_bias=False, dtype=jnp.bfloat16)(out)
+
+class Block(nn.Module):
+    @nn.compact
+    def __call__(self, x, mask):
+        h = RMSNorm(D_MODEL)(x)
+        h = Attention()(h, mask)
+        x = x + h
+
+        h = RMSNorm(D_MODEL)(x)
+        h = nn.Dense(D_FF, dtype=jnp.bfloat16)(h)
+        h = nn.gelu(h)
+        h = nn.Dense(D_MODEL, dtype=jnp.bfloat16)(h)
+
+        return x + h
+
+class GPT(nn.Module):
+    @nn.compact
+    def __call__(self, input_ids):
+        batch, seq_len = input_ids.shape
+        mask = nn.attention.make_causal_mask(
+            jnp.ones((batch, seq_len), dtype=jnp.bool_)
+        )
+
+        x = nn.Embed(
+            VOCAB_SIZE,
+            D_MODEL,
+            embedding_init=nn.initializers.normal(0.02),
+            dtype=jnp.bfloat16,
+        )(input_ids)
+
+        RematBlock = nn.remat(Block)
+
+        for _ in range(N_LAYERS):
+            x = RematBlock()(x, mask)
+
+        x = RMSNorm(D_MODEL)(x)
+
+        return nn.Dense(
+            VOCAB_SIZE,
+            use_bias=False,
+            dtype=jnp.bfloat16
+        )(x)
+# ---------------- LOAD CHECKPOINT ----------------
+def create_state():
+    model = GPT()
+    rng = jax.random.PRNGKey(0)
+    params = model.init(rng, jnp.ones((1, SEQ_LEN), dtype=jnp.int32))
+    return train_state.TrainState.create(
+        apply_fn=model.apply,
+        params=params,
+        tx=optax.adamw(1e-4),
+    )
+
+state = create_state()
+state = checkpoints.restore_checkpoint(CKPT_PATH, state)
+params = state.params
+model = GPT()
+
+print("Checkpoint loaded.")
+
+@jax.jit
+def forward(params, input_ids):
+    return model.apply(params, input_ids)
+
+import jax.random as random
+
+def generate(params, input_ids, max_new_tokens=30, temperature=0.9, top_k=40):
+    rng = random.PRNGKey(0)
+
+    for _ in range(max_new_tokens):
+
+        logits = model.apply(params, input_ids)
+        logits = logits[:, -1, :]
+        logits = logits.astype(jnp.float32)
+
+        logits = logits / temperature
+
+        top_k_logits, top_k_indices = jax.lax.top_k(logits, top_k)
+        probs = jax.nn.softmax(top_k_logits, axis=-1)
+
+        rng, subkey = random.split(rng)
+        next_token_idx = random.categorical(subkey, jnp.log(probs))
+
+        next_token = jnp.take_along_axis(
+            top_k_indices,
+            next_token_idx[:, None],
+            axis=-1
+        )
+
+        input_ids = jnp.concatenate([input_ids, next_token], axis=1)
+
+    return input_ids
+# ---------------- RUN ----------------
+tokenizer = AutoTokenizer.from_pretrained("autonomousX/Instinct-1B")
+
+prompt = "I am John,"
+tokens = tokenizer(prompt, return_tensors="np")
+input_ids = jnp.array(tokens["input_ids"], dtype=jnp.int32)
+
+output_ids = generate(params, input_ids, 200)
+
+print("\n=== GENERATED TEXT ===\n")
+print(tokenizer.decode(output_ids[0].tolist()))
+```
+</details>