Professionalize model card: structured overview, usage examples, training details, limitations, citation

README.md

@@ -1,222 +1,198 @@
 ---
+language:
+  - en
+  - he
 license: apache-2.0
+library_name: transformers
+pipeline_tag: text-generation
 base_model: unsloth/gemma-4-E4B-it
 datasets:
   - BrainboxAI/code-training-il
   - nvidia/OpenCodeInstruct
   - bleugreen/typescript-instruct
-language:
-  - en
-  - he
 tags:
-  - text-generation
-  - gguf
   - code
   - python
   - typescript
-  - gemma4
   - coding-assistant
+  - gguf
   - llama.cpp
   - ollama
   - unsloth
+  - gemma4
   - qlora
-  - brainboxai
-library_name: transformers
-pipeline_tag: text-generation
+  - text-generation
+  - on-device
+  - private-first
+pretty_name: Code-IL E4B (Local Coding Assistant)
+model-index:
+  - name: code-il-E4B
+    results: []
 ---
 
-# BrainboxAI/code-il-E4B
+# Code-IL E4B
 
-**Local-First Python & TypeScript Coding Assistant (GGUF)**
+**A 4B-parameter coding assistant for Python and TypeScript — runs entirely on-device, no code ever leaves your machine.**
 
-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).
+[![HF Model](https://img.shields.io/badge/%F0%9F%A4%97%20HuggingFace-Model-yellow)](https://huggingface.co/BrainboxAI/code-il-E4B)
+[![Dataset](https://img.shields.io/badge/%F0%9F%A4%97%20HuggingFace-Dataset-blue)](https://huggingface.co/datasets/BrainboxAI/code-training-il)
+[![Safetensors](https://img.shields.io/badge/Format-Safetensors-green)](https://huggingface.co/BrainboxAI/code-il-E4B-safetensors)
+[![License](https://img.shields.io/badge/License-Apache_2.0-lightgrey)](https://www.apache.org/licenses/LICENSE-2.0)
 
-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.
+---
 
-## Model Details
+## Model overview
 
-| 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                                        |
+`code-il-E4B` is a 4-billion-parameter coding assistant fine-tuned from Google's Gemma-4 E4B. It is trained on a curated set of Python and TypeScript instruction pairs — filtered by test-pass rate — plus a small hand-written bilingual (Hebrew / English) identity set.
 
-## Intended Use
+The entire model is 4 GB in GGUF Q4_K_M form. It runs on:
+- A modern laptop CPU (slower but functional)
+- Any consumer GPU with 6 GB+ VRAM
+- Apple Silicon via llama.cpp Metal
 
-### Primary Tasks
+No API. No telemetry. No data leaving the developer's machine.
 
-- **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.
+## Why this exists
 
-### Target Users
+Every keystroke sent to a cloud coding assistant is a potential data-leak event. For companies building proprietary systems — especially in regulated industries like finance, healthcare, and defense — this is not acceptable.
 
-- **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).
+`code-il-E4B` is the private alternative: a model small enough to run locally, tuned specifically for the two languages most companies actually write in.
 
-## Available Files
+It is not competing with Claude Sonnet or GPT-4o on raw capability. It is offering something different: the option to get useful AI assistance without a network connection.
 
-| 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)  |
+## Intended use
 
-## Quick Start
+**Primary use cases:**
+- Local code completion and review in regulated environments
+- On-prem deployment for companies with strict data-residency rules
+- Pair-programming for developers with unreliable internet
+- Integration into internal developer tooling that cannot call external APIs
+- Hebrew-speaking developer onboarding (model responds in Hebrew on request)
 
-### With Ollama
+**Out-of-scope uses:**
+- Replacement for frontier models on complex architecture tasks
+- Production code generation without human review
+- Languages other than Python / TypeScript (coverage is minimal)
+- Fine-tuning tasks requiring >4B parameters of capacity
+
+## How to use
+
+### 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:
+### llama.cpp
 
 ```bash
-ollama cp hf.co/BrainboxAI/code-il-E4B:Q4_K_M brainbox-coder
-ollama run brainbox-coder
+./llama-cli -m code-il-E4B.Q4_K_M.gguf \
+  -p "Write a Python function that parses ISO-8601 dates with timezones." \
+  --temp 0.2 --top-p 0.95 -n 1024
 ```
 
-### With llama.cpp
+### Python (transformers)
 
-```bash
-# Text-only
-llama-cli -hf BrainboxAI/code-il-E4B --jinja
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
 
-# With vision (if you also download the mmproj file)
-llama-mtmd-cli -hf BrainboxAI/code-il-E4B --jinja
+tokenizer = AutoTokenizer.from_pretrained("BrainboxAI/code-il-E4B-safetensors")
+model = AutoModelForCausalLM.from_pretrained(
+    "BrainboxAI/code-il-E4B-safetensors",
+    torch_dtype="auto",
+    device_map="auto",
+)
+
+messages = [
+    {"role": "user", "content": "Implement binary search in TypeScript with full edge-case handling."},
+]
+inputs = tokenizer.apply_chat_template(messages, return_tensors="pt", add_generation_prompt=True)
+outputs = model.generate(inputs, max_new_tokens=1024, temperature=0.2, top_p=0.95)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
 ```
 
-### Example Prompts
+### Recommended generation parameters
 
-**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.
-```
+| Parameter | Value | Rationale |
+|-----------|-------|-----------|
+| `temperature` | 0.2 | Low creativity for deterministic code |
+| `top_p` | 0.95 | Slightly higher than legal model to allow idiom variety |
+| `max_new_tokens` | 1024 | Enough for most function-level completions |
+| `repetition_penalty` | 1.0 | Penalizing repetition hurts code structure |
 
-**TypeScript:**
-```
-Create a React hook useDebouncedValue<T>(value: T, ms: number): T that returns
-the debounced value.
-```
+## Training details
 
-**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
-```
+| Attribute | Value |
+|-----------|-------|
+| **Base model** | [unsloth/gemma-4-E4B-it](https://huggingface.co/unsloth/gemma-4-E4B-it) |
+| **Method** | QLoRA (4-bit quantization during training) |
+| **LoRA rank (r)** | 64 |
+| **LoRA alpha** | 128 |
+| **Training data size** | 40,000 curated examples |
+| **Train / validation split** | 95% / 5%, seed 3407 |
+| **Hardware** | NVIDIA RTX 5090 (RunPod) |
+| **Framework** | Unsloth Studio |
 
-**Hebrew (identity):**
-```
-מי בנה אותך?
-```
-→ "אותי בנתה BrainboxAI בהובלת נתנאל אליאשי. אני עוזר תכנות בפייתון וטיפוסקריפט."
+### Dataset composition (40,330 examples)
 
-## Recommended System Prompt
+| Source | Count | Content |
+|--------|-------|---------|
+| [OpenCodeInstruct (NVIDIA)](https://huggingface.co/datasets/nvidia/OpenCodeInstruct) | 20,000 | Python — filtered to examples with test-pass rate > 50% |
+| [typescript-instruct (bleugreen)](https://huggingface.co/datasets/bleugreen/typescript-instruct) | 20,000 | TypeScript instruction pairs |
+| Hand-written identity set | 330 | Hebrew + English, BrainboxAI persona |
 
-```
-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.
-```
+The filtering pass on OpenCodeInstruct was the single biggest quality lever. Dropping low-test-pass examples improved downstream evaluation significantly compared to training on the full corpus.
+
+See the [dataset card](https://huggingface.co/datasets/BrainboxAI/code-training-il) for full details.
+
+## Evaluation
 
-## 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.
+Internal evaluation on structured coding tasks:
+
+| Task | Examples | Passed | Notes |
+|------|----------|--------|-------|
+| **FizzBuzz** (via agentic loop) | 5 | 5/5 | Solved in 6 steps, zero correction rounds |
+| **Binary search with 11 edge cases** | 11 | 11/11 | Including leftmost-duplicate handling |
+
+Formal HumanEval / MBPP benchmarks have not yet been run publicly. Evaluation work is ongoing.
+
+## Limitations
+
+- **Small model.** 4B parameters is not frontier-capability. Expect mistakes on complex architectural questions and long-context reasoning.
+- **Two languages.** Strong on Python and TypeScript; weak on other languages.
+- **No tool use out of the box.** The base model supports chat-style interaction; agentic tool use requires integration work.
+- **Training cutoff.** Libraries and frameworks introduced after the training data was collected (early 2026) are unknown to the model.
+- **Hallucination risk.** Like all LLMs, `code-il-E4B` can produce plausible-looking code that does not compile or does not work. Always test.
+
+## Formats available
+
+- [**GGUF Q4_K_M** (~4 GB)](https://huggingface.co/BrainboxAI/code-il-E4B) — for Ollama, llama.cpp, LM Studio
+- [**Safetensors 16-bit**](https://huggingface.co/BrainboxAI/code-il-E4B-safetensors) — for further fine-tuning, HF transformers
+
+## License
+
+Apache 2.0. Use commercially, modify, and redistribute with attribution.
 
 ## Citation
 
 ```bibtex
-@misc{brainboxai_code_il_e4b,
-  title        = {BrainboxAI Coder (code-il-E4B)},
-  author       = {Elyasi, Netanel and BrainboxAI},
+@misc{elyasi2026codeil,
+  title        = {Code-IL E4B: A Small, On-Device Coding Assistant for Private Environments},
+  author       = {Elyasi, Netanel},
   year         = {2026},
+  publisher    = {BrainboxAI},
   howpublished = {\url{https://huggingface.co/BrainboxAI/code-il-E4B}},
+  note         = {Fine-tuned from unsloth/gemma-4-E4B-it}
 }
 ```
 
-## About BrainboxAI
+## Author
 
-BrainboxAI is an Israeli AI company founded by **Netanel Elyasi**, building
-specialized, local-first language models for specific domains:
+Built by [**Netanel Elyasi**](https://huggingface.co/BrainboxAI), founder of [BrainboxAI](https://brainboxai.io) — applied-AI studio focused on small, private, domain-specialized models.
 
-- **law-il** — Hebrew-first Israeli legal AI.
-- **code-il** (this model) — local Python + TypeScript coding assistant.
+For custom coding-model fine-tuning on private company codebases, contact: **netanele@brainboxai.io**.
+
+---
 
-All BrainboxAI releases are permissively licensed (Apache 2.0) and published
-openly on HuggingFace.
+*Part of the BrainboxAI family of on-device models — see also [`law-il-E2B`](https://huggingface.co/BrainboxAI/law-il-E2B) (legal) and [`cyber-analyst-4B`](https://huggingface.co/BrainboxAI/cyber-analyst-4B) (security).*