Upload README.md

README.md

@@ -1,133 +1,133 @@
----
-tags:
-- ml-intern
-- ethical-hacking
-- cybersecurity
-- unsloth
-- colab
----
+# 🔐 Ethical Hacking LLM Collection — Google Colab Free Tier (T4)
 
-# 🔐 Ethical Hacking LLM Fine-Tuning Collection
+A curated collection of **production-ready Colab notebooks** for fine-tuning state-of-the-art small LLMs on **defensive cybersecurity / ethical hacking** tasks using **Google Colab Free Tier (T4, 16GB VRAM)**.
 
-> **Public collection of Colab-ready notebooks for fine-tuning cybersecurity/ethical hacking LLMs on Google Colab Free Tier (T4 GPU, ~16GB VRAM).**
+> ⚠️ **All datasets are defensive/educational.** We only train on pentesting methodology, threat analysis, incident response, and CTF education — never malicious payloads or active attack instructions.
 
 ---
 
-## 📦 What's Included
+## 📚 Notebooks
 
-| File | Model | Description |
-|------|-------|-------------|
-| `EthicalHacking_Qwen3-4B_Ultimate_Colab.ipynb` | **Qwen3-4B-Instruct-2507** 🥇 | Best coding/reasoning under 10B. **Recommended for T4.** |
-| `EthicalHacking_Qwen3-8B_Colab.ipynb` | Qwen3-8B | More capacity, tighter VRAM. Simpler notebook. |
-| `EthicalHacking_MultiModel_Comparison_Colab.ipynb` | **Multi-model selector** | Pick between Qwen3-4B/8B or Gemma-3-4B in one notebook |
+| Notebook | Model | Size | T4 Batch | Est. Time | Status |
+|----------|-------|------|----------|-----------|--------|
+| [**Qwen3-4B Ultimate**](./EthicalHacking_Qwen3-4B_Ultimate_Colab.ipynb) | `unsloth/Qwen3-4B-Instruct-2507` | 3.3GB 4-bit | **4** | ~3–4 hrs | ✅ Recommended |
+| [**LFM2.5 Ultimate**](./EthicalHacking_LFM2.5_Ultimate_Colab.ipynb) | `unsloth/LFM2.5-1.2B-Instruct` | ~1GB 4-bit | **8** | ~1–2 hrs | ✅ Fastest |
+| [**Gemma-4 E2B**](./EthicalHacking_Gemma4_E2B_Colab.ipynb) | `unsloth/gemma-4-E2B-it` | ~7.6GB 4-bit | **1** | ~6–8 hrs | ⚠️ Tight VRAM |
+| **Bonsai (PrismML)** | See [limitations](./BONSAI_LIMITATIONS.md) | ~1GB 1-bit | N/A | N/A | ❌ Not supported |
 
 ---
 
-## 🚨 CRITICAL FIX: `formatting_func` Required by Unsloth
+## 🥇 Model Comparison (May 2026)
 
-If you get this error:
-```
-RuntimeError: Unsloth: You must specify a formatting_func
-```
+| Model | Params | 4-bit Size | VRAM Fit | Batch | MMLU-Pro | LiveCodeBench | Context | Notes |
+|-------|--------|-----------|----------|-------|----------|---------------|---------|-------|
+| **Qwen3-4B** | 4B | 3.3 GB | Easy (12GB free) | 4 | 69.6 | **35.1** | 32K | Best coding/reasoning ratio. Thinking toggle. |
+| **LFM2.5-1.2B** | 1.2B | **~1 GB** | Huge headroom | 8 | — | — | **128K** | Fastest training. Liquid AI edge model. |
+| **Gemma-4 E2B** | ~2B dense | 7.6 GB | Tight (8GB free) | 1 | — | — | 256K | Dense (not MoE). Google edge model. |
+| Bonsai-8B | 8B | ~1 GB packed | N/A | N/A | ~30 | — | — | 1-bit ternary. **Cannot train with Unsloth.** |
 
-**The fix:** When using `FastLanguageModel` + `SFTTrainer`, Unsloth **requires** you to explicitly pass a `formatting_func` that converts `messages` → text string:
+**Recommendation:** Start with **Qwen3-4B** for best accuracy, or **LFM2.5** for fastest experimentation.
 
-```python
-def formatting_func(example):
-    return tokenizer.apply_chat_template(
-        example["messages"],
-        tokenize=False,              # MUST be False!
-        add_generation_prompt=False,
-    )
-
-trainer = SFTTrainer(
-    model=model,
-    train_dataset=dataset,
-    formatting_func=formatting_func,  # ← REQUIRED
-    ...
-)
-```
+---
 
-All notebooks in this repo now include this fix.
+## 🚀 How to Use (Any Notebook)
 
----
+1. Open the notebook in **Google Colab** (click the notebook link above)
+2. Runtime → Change runtime type → **T4 GPU**
+3. Run cells top-to-bottom
+4. (Optional) Set your HF token in cell 2 to push the LoRA adapter
+5. The last cells show **inference demos** and a **CyberMetric benchmark**
+
+**Zero-config:** All hyperparameters are tuned for T4. Just click ▶️ and train.
 
-## 🏆 Model Comparison (T4 16GB, May/June 2026)
+---
 
-| Model | 4-bit Size | T4 Fit | Coding Benchmarks | Unsloth | Verdict |
-|-------|-----------|--------|------------------|---------|---------|
-| **Qwen3-4B-Instruct-2507** 🥇 | **3.3 GB** | ✅✅✅ Excellent | LiveCodeBench 35.1, MultiPL-E 76.8 | ✅ Confirmed | **USE THIS** |
-| Qwen3-8B | 7.0 GB | ✅✅ Good | Stronger base | ✅ Confirmed | Viable |
-| Gemma-3-4B | ~2.5 GB | ✅✅✅ Excellent | Decent | ✅ Confirmed | Alternative |
-| Gemma-4-E2B | ~7.6 GB | ✅✅ Good | Unverified | ⚠️ Limited | Experimental |
-| **Bonsai** (prism-ml) | ~0.5 GB | ✅✅✅ Excellent | Weak (MMLU ~30%) | ❌ No | **AVOID** |
-| **LFM2** (Liquid AI) | ~2.5 GB | ✅✅ Good | **Not for programming** | ❌ No | **AVOID** |
+## 📊 Datasets
 
-### Key Datasets Used
+Both notebooks use the same **merged + subsampled** dataset:
 
 | Dataset | Rows | Focus |
 |---------|------|-------|
-| [Fenrir v2.1](https://huggingface.co/datasets/AlicanKiraz0/Cybersecurity-Dataset-Fenrir-v2.1) | 99,870 | Threat analysis, IR, offensive education |
-| [Trendyol Cybersecurity](https://huggingface.co/datasets/Trendyol/Trendyol-Cybersecurity-Instruction-Tuning-Dataset) | 53,202 | C2 analysis, forensics, 200+ topics |
+| [Fenrir v2.1](https://huggingface.co/datasets/AlicanKiraz0/Cybersecurity-Dataset-Fenrir-v2.1) | 99,870 | Causal reasoning, threat analysis, IR |
+| [Trendyol Cybersecurity](https://huggingface.co/datasets/Trendyol/Trendyol-Cybersecurity-Instruction-Tuning-Dataset) | 53,202 | 200+ topics, C2 analysis, forensics |
+| **Merged** | 153,072 | — |
+| **Subsampled** | **50,000** | Enough for LoRA convergence |
 
 ---
 
-## 🚀 Quick Start
+## 🔧 Key Technical Decisions
 
-1. Open [Google Colab](https://colab.research.google.com)
-2. **Runtime → Change runtime type → GPU (T4)**
-3. Upload the `.ipynb` file from this repo
-4. **Run all cells** — training takes ~1.5–2.5 hours for 1 epoch
+### Why `dataset_text_field="text"` instead of `formatting_func`
 
----
+Unsloth's `SFTTrainer` has issues with `formatting_func` when using `FastLanguageModel`. The cleanest fix used in all notebooks:
+
+```python
+# Pre-convert messages → text using dataset.map(batched=True)
+def convert_messages_to_text(examples):
+    texts = []
+    for msgs in examples["messages"]:
+        text = tokenizer.apply_chat_template(msgs, tokenize=False)
+        texts.append(text)
+    return {"text": texts}
+
+train_dataset = train_dataset.map(convert_messages_to_text, batched=True, remove_columns=["messages"])
+
+# Then pass dataset_text_field="text" to SFTTrainer — no formatting_func needed
+trainer = SFTTrainer(..., dataset_text_field="text")
+```
 
-## ⚙️ T4 VRAM Optimizations Used
+### Speed Optimizations (Qwen3-4B v2)
 
-- `load_in_4bit=True` + LoRA (r=64 for 4B, r=16 for 8B)
-- `adamw_8bit` optimizer
-- `use_gradient_checkpointing="unsloth"`
-- `fp16=True` (T4 has no bf16)
-- Batch=2, Accum=4 → effective batch=8
+| Setting | v1 | v2 | Impact |
+|---------|-----|-----|--------|
+| Dataset | 153K rows | **50K rows** | 3× fewer steps |
+| Batch size | 2 | **4** | 2× throughput |
+| Grad accum | 4 | **2** | Same effective batch |
+| Packing | False | **True** | 2–3× GPU utilization |
+| Max steps | 19K (full epoch) | **4,000** | Loss already plateaus |
+| **Est. time** | ~45 hrs | **~3–4 hrs** | Same quality |
 
 ---
 
-## 🛡️ Disclaimer
-
-All datasets are **defensive/educational** (pentesting methodology, threat analysis, incident response). Intended for **ethical hacking education and security research** only.
+## 📖 Model-Specific Links
 
----
+### Qwen3-4B
+- Model: https://huggingface.co/Qwen/Qwen3-4B-Instruct-2507
+- Unsloth 4-bit: https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-unsloth-bnb-4bit
 
-## 📚 References
+### LFM2.5
+- Docs: https://unsloth.ai/docs/models/tutorials/lfm2.5
+- Unsloth notebook: https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Liquid_LFM2_(1.2B)-Conversational.ipynb
 
-| Resource | Link |
-|----------|------|
-| Qwen3-4B-Instruct-2507 | https://huggingface.co/Qwen/Qwen3-4B-Instruct-2507 |
-| Unsloth 4-bit | https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-unsloth-bnb-4bit |
-| Unsloth Docs | https://unsloth.ai/docs |
-| TRL SFTTrainer | https://huggingface.co/docs/trl/sft_trainer |
-| Fenrir Dataset | https://huggingface.co/datasets/AlicanKiraz0/Cybersecurity-Dataset-Fenrir-v2.1 |
-| Trendyol Dataset | https://huggingface.co/datasets/Trendyol/Trendyol-Cybersecurity-Instruction-Tuning-Dataset |
-| CyberMetric Eval | https://huggingface.co/datasets/cybermetric/cybermetric-500 |
+### Gemma-4 E2B
+- Docs: https://unsloth.ai/docs/models/gemma-4/train
+- Unsloth notebook: https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma4_(E2B)-Text.ipynb
 
 ---
-*Built with ❤️ for the cybersecurity community. Use responsibly.*
-
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
 
-This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub.
+## ⚠️ T4 VRAM Cheat-Sheet
 
-- Try ML Intern: https://smolagents-ml-intern.hf.space
-- Source code: https://github.com/huggingface/ml-intern
+| Symptom | Fix |
+|---------|-----|
+| `CUDA out of memory` | Lower `MAX_SEQ_LENGTH` to 2048; set `BATCH_SIZE=1`; set `PACKING=False` |
+| Still OOM | Enable `use_rslora=True` in LoRA config |
+| Training very slow | Increase `BATCH_SIZE` if VRAM allows; enable `PACKING=True` |
+| Loss not decreasing | Try `LEARNING_RATE=5e-4` or train for 2 epochs |
+| Can't push to Hub | Run `login(token=...)` with a **WRITE** token |
 
-## Usage
+---
 
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
+## 📂 Repository Structure
 
-model_id = "asdf98/ethical-hacking-llm-colab"
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id)
+```
+asdf98/ethical-hacking-llm-colab/
+├── EthicalHacking_Qwen3-4B_Ultimate_Colab.ipynb   ← Best accuracy (recommended)
+├── EthicalHacking_LFM2.5_Ultimate_Colab.ipynb     ��� Fastest training
+├── EthicalHacking_Gemma4_E2B_Colab.ipynb          ← Google model (tight VRAM)
+├── BONSAI_LIMITATIONS.md                          ← Why Bonsai can't be fine-tuned
+└── README.md                                      ← This file
 ```
 
-For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class.
+---
+
+*Built with ❤️ for the cybersecurity community. Use responsibly.*