Upload README.md

README.md

@@ -1,31 +1,222 @@
 ---
+license: apache-2.0
+base_model: unsloth/gemma-4-E4B-it
+datasets:
+  - BrainboxAI/code-training-il
+  - nvidia/OpenCodeInstruct
+  - bleugreen/typescript-instruct
+language:
+  - en
+  - he
 tags:
-- gguf
-- llama.cpp
-- unsloth
-- vision-language-model
+  - text-generation
+  - gguf
+  - code
+  - python
+  - typescript
+  - gemma4
+  - coding-assistant
+  - llama.cpp
+  - ollama
+  - unsloth
+  - qlora
+  - brainboxai
+library_name: transformers
+pipeline_tag: text-generation
 ---
 
-# code-il-E4B : GGUF
+# BrainboxAI/code-il-E4B
 
-This model was finetuned and converted to GGUF format using [Unsloth](https://github.com/unslothai/unsloth).
+**Local-First Python & TypeScript Coding Assistant (GGUF)**
 
-**Example usage**:
-- For text only LLMs:    `llama-cli -hf BrainboxAI/code-il-E4B --jinja`
-- For multimodal models: `llama-mtmd-cli -hf BrainboxAI/code-il-E4B --jinja`
+Built by [**BrainboxAI**](https://huggingface.co/BrainboxAI), founded by **Netanel Elyasi**.
+Sister model of [BrainboxAI/law-il-E2B](https://huggingface.co/BrainboxAI/law-il-E2B).
 
-## Available Model files:
-- `gemma-4-e4b-it.Q4_K_M.gguf`
-- `gemma-4-e4b-it.BF16-mmproj.gguf`
+A lightweight coding model, fine-tuned from Google's Gemma 4 E4B on ~40K Python and
+TypeScript instruction pairs plus a hand-curated identity set. Designed to run locally
+via Ollama or llama.cpp with no cloud API, no rate limits, and no data leaving the machine.
 
-## ⚠️ Ollama Note for Vision Models
-**Important:** Ollama currently does not support separate mmproj files for vision models.
+## Model Details
 
-To create an Ollama model from this vision model:
-1. Place the `Modelfile` in the same directory as the finetuned bf16 merged model
-3. Run: `ollama create model_name -f ./Modelfile`
-   (Replace `model_name` with your desired name)
+| Attribute         | Value                                                              |
+|-------------------|--------------------------------------------------------------------|
+| **Base Model**    | [unsloth/gemma-4-E4B-it](https://huggingface.co/unsloth/gemma-4-E4B-it) (4B params) |
+| **Architecture**  | Gemma4ForConditionalGeneration                                     |
+| **Context Length**| 128K tokens (inherited from base)                                  |
+| **Training**      | QLoRA 4-bit with Unsloth (2x faster training)                      |
+| **Dataset**       | [BrainboxAI/code-training-il](https://huggingface.co/datasets/BrainboxAI/code-training-il) (~40K examples) |
+| **Quantization**  | Q4_K_M GGUF (~5.3 GB)                                              |
+| **License**       | Apache 2.0                                                         |
+| **Author**        | Netanel Elyasi · BrainboxAI                                        |
 
-This will create a unified bf16 model that Ollama can use.
-This was trained 2x faster with [Unsloth](https://github.com/unslothai/unsloth)
-[<img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" width="200"/>](https://github.com/unslothai/unsloth)
+## Intended Use
+
+### Primary Tasks
+
+- **Python code generation** — functions, classes, algorithms, data structures.
+- **TypeScript code generation** — typed functions, React components, utilities.
+- **Debugging** — trace exceptions, explain errors, suggest fixes.
+- **Code explanation** — walk through existing snippets in English or Hebrew.
+- **Test writing** — pytest (Python), Jest/assertion-style (TypeScript).
+- **Refactoring** — simplify, extract helpers, improve readability.
+
+### Target Users
+
+- **Developers** who want local-first coding help without sending code to cloud APIs.
+- **Privacy-sensitive teams** building products that can't leak internal code.
+- **Offline workflows** — on the train, on a plane, behind a restrictive firewall.
+- **Hobbyists** running on modest hardware (6 GB+ VRAM or CPU-only).
+
+## Available Files
+
+| File                                     | Size     | Use                                                 |
+|------------------------------------------|---------:|-----------------------------------------------------|
+| `gemma-4-e4b-it.Q4_K_M.gguf`             | 5.34 GB  | Main model — Ollama / llama.cpp local inference      |
+| `gemma-4-e4b-it.BF16-mmproj.gguf`        | ~0.9 GB  | Vision projector (optional — base supports vision)  |
+
+## Quick Start
+
+### With Ollama
+
+```bash
+ollama pull hf.co/BrainboxAI/code-il-E4B:Q4_K_M
+ollama run hf.co/BrainboxAI/code-il-E4B:Q4_K_M
+```
+
+Optional — tag it with a short name:
+
+```bash
+ollama cp hf.co/BrainboxAI/code-il-E4B:Q4_K_M brainbox-coder
+ollama run brainbox-coder
+```
+
+### With llama.cpp
+
+```bash
+# Text-only
+llama-cli -hf BrainboxAI/code-il-E4B --jinja
+
+# With vision (if you also download the mmproj file)
+llama-mtmd-cli -hf BrainboxAI/code-il-E4B --jinja
+```
+
+### Example Prompts
+
+**Python:**
+```
+Write a Python function that returns the leftmost index of a target in a sorted
+array with possible duplicates, or -1 if not found.
+```
+
+**TypeScript:**
+```
+Create a React hook useDebouncedValue<T>(value: T, ms: number): T that returns
+the debounced value.
+```
+
+**Debugging:**
+```
+This pytest fails with AssertionError. What's wrong with my binary_search?
+
+def binary_search(arr, target):
+    lo, hi = 0, len(arr)
+    while lo < hi:
+        mid = (lo + hi) // 2
+        if arr[mid] == target: return mid
+        elif arr[mid] < target: lo = mid + 1
+        else: hi = mid - 1
+    return -1
+```
+
+**Hebrew (identity):**
+```
+מי בנה אותך?
+```
+→ "אותי בנתה BrainboxAI בהובלת נתנאל אליאשי. אני עוזר תכנות בפייתון וטיפוסקריפט."
+
+## Recommended System Prompt
+
+```
+You are BrainboxAI Coder, a local coding assistant fine-tuned from Gemma 4 by
+Netanel Elyasi at BrainboxAI. You specialize in Python and TypeScript.
+
+Prefer concise, correct code over verbose explanations. Always:
+- Include obvious imports in generated files.
+- When writing tests, match the current implementation unless asked to change it.
+- Return -1 / None / null honestly when a value is missing rather than raising.
+- Flag when the user's request has multiple interpretations and ask a short clarifying question.
+```
+
+## Training Details
+
+| Stage                  | Value                                              |
+|------------------------|----------------------------------------------------|
+| **Method**             | QLoRA 4-bit supervised fine-tuning (SFT)           |
+| **Framework**          | Unsloth + TRL `SFTTrainer`                         |
+| **Hardware**           | NVIDIA RTX 5090 (32 GB VRAM)                       |
+| **LoRA rank**          | 16 (alpha 16, dropout 0)                           |
+| **Target modules**     | q_proj, k_proj, v_proj, o_proj, gate/up/down_proj  |
+| **Batch**              | 2 × 4 grad accum = 16 effective                    |
+| **Learning rate**      | 2e-4, linear decay, 10-step warmup                 |
+| **Steps**              | 500                                                |
+| **Sequence length**    | 2,048 tokens                                       |
+| **Final loss**         | ~0.8 (from ~2.4 average at start)                  |
+| **Gradient checkpointing** | `"unsloth"` (≈30% VRAM savings)                |
+| **Seed**               | 3407                                               |
+
+## Dataset
+
+Trained on [BrainboxAI/code-training-il](https://huggingface.co/datasets/BrainboxAI/code-training-il):
+
+| Source                              | Samples | Language         |
+|-------------------------------------|--------:|------------------|
+| nvidia/OpenCodeInstruct (score≥0.5) |  20,000 | English / Python |
+| bleugreen/typescript-instruct       |  20,000 | English / TS     |
+| BrainboxAI identity examples        |     330 | EN + HE          |
+
+Split 95/5 train/eval (seed 3407).
+
+## Limitations & Ethical Considerations
+
+- **4B parameters.** Competitive with larger models on everyday Python/TypeScript
+  tasks but will not match GPT-4 or Claude on novel algorithms, complex system
+  design, or long multi-file reasoning.
+- **Two languages only.** Python and TypeScript. Generation quality on Rust, Go,
+  C++, Ruby, etc. will be noticeably weaker.
+- **Identity is hard-coded.** The model will assert it is "BrainboxAI Coder,
+  trained by Netanel Elyasi at BrainboxAI" across sessions.
+- **Cutoff.** Training data reflects code up to the dataset snapshot (2026).
+  Library APIs released afterwards may be missing.
+- **Not a security auditor.** The model can be prompted to produce insecure code.
+  Always review generated code before running in production.
+- **Hallucinations.** Like any LLM, it can fabricate imports, function signatures,
+  or test cases. Verify everything.
+
+## Sibling Repositories
+
+- [BrainboxAI/code-training-il](https://huggingface.co/datasets/BrainboxAI/code-training-il) — training dataset (this model).
+- [BrainboxAI/law-il-E2B](https://huggingface.co/BrainboxAI/law-il-E2B) — Israeli legal assistant.
+- [BrainboxAI/law-il-E2B-safetensors](https://huggingface.co/BrainboxAI/law-il-E2B-safetensors) — safetensors variant.
+- [BrainboxAI/legal-training-il](https://huggingface.co/datasets/BrainboxAI/legal-training-il) — legal training dataset.
+
+## Citation
+
+```bibtex
+@misc{brainboxai_code_il_e4b,
+  title        = {BrainboxAI Coder (code-il-E4B)},
+  author       = {Elyasi, Netanel and BrainboxAI},
+  year         = {2026},
+  howpublished = {\url{https://huggingface.co/BrainboxAI/code-il-E4B}},
+}
+```
+
+## About BrainboxAI
+
+BrainboxAI is an Israeli AI company founded by **Netanel Elyasi**, building
+specialized, local-first language models for specific domains:
+
+- **law-il** — Hebrew-first Israeli legal AI.
+- **code-il** (this model) — local Python + TypeScript coding assistant.
+
+All BrainboxAI releases are permissively licensed (Apache 2.0) and published
+openly on HuggingFace.