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

README.md

@@ -3,7 +3,11 @@ language:
   - he
   - en
 license: apache-2.0
+library_name: transformers
+pipeline_tag: text-generation
 base_model: unsloth/gemma-4-E2B-it
+datasets:
+  - BrainboxAI/legal-training-il
 tags:
   - legal
   - law
@@ -13,224 +17,185 @@ tags:
   - kol-zchut
   - gguf
   - llama.cpp
+  - ollama
   - unsloth
   - gemma4
-  - vision-language-model
+  - qlora
   - conversational
-pipeline_tag: text-generation
-datasets:
-  - BrainboxAI/legal-training-il
-pretty_name: BrainboxAI Law IL E2B
+  - text-generation
+  - on-device
+pretty_name: Law-IL E2B (Israeli Legal AI)
+model-index:
+  - name: law-il-E2B
+    results: []
 ---
 
-# BrainboxAI/law-il-E2B
-
-### Hebrew-First Israeli Legal AI Specialist (GGUF)
+# Law-IL E2B
 
-A Gemma 4 E2B model fine-tuned by **BrainboxAI** for Israeli legal Q&A, court ruling analysis, rights explanations (כל-זכות), and contract clause interpretation - bilingual Hebrew and English, optimized for local inference.
+**A 2B-parameter Israeli legal reasoning model, fine-tuned to cite statute, apply precedent, and respond in fluent Hebrew — runs entirely on a laptop.**
 
-Built and maintained by **[BrainboxAI](https://huggingface.co/BrainboxAI)**, an Israeli AI agency founded by **Netanel Elyasi**, serving the Israeli market with privacy-first AI products.
+[![HF Model](https://img.shields.io/badge/%F0%9F%A4%97%20HuggingFace-Model-yellow)](https://huggingface.co/BrainboxAI/law-il-E2B)
+[![Dataset](https://img.shields.io/badge/%F0%9F%A4%97%20HuggingFace-Dataset-blue)](https://huggingface.co/datasets/BrainboxAI/legal-training-il)
+[![Safetensors](https://img.shields.io/badge/Format-Safetensors-green)](https://huggingface.co/BrainboxAI/law-il-E2B-safetensors)
+[![License](https://img.shields.io/badge/License-Apache_2.0-lightgrey)](https://www.apache.org/licenses/LICENSE-2.0)
 
 ---
 
-## Model Details
+## Model overview
 
-| Attribute | Value |
-|-----------|-------|
-| **Base Model** | [unsloth/gemma-4-E2B-it](https://huggingface.co/unsloth/gemma-4-E2B-it) (Gemma 4 Efficient 2B Instruct) |
-| **Architecture** | Gemma4ForConditionalGeneration (text + vision + audio) |
-| **Parameters** | ~2B |
-| **Context Length** | 131,072 tokens |
-| **Languages** | Hebrew, English |
-| **Training Framework** | Unsloth (2x faster fine-tuning) |
-| **Training Dataset** | [BrainboxAI/legal-training-il](https://huggingface.co/datasets/BrainboxAI/legal-training-il) |
-| **License** | Apache 2.0 |
+`law-il-E2B` is an instruction-tuned small language model specialized for Israeli legal work. It is built on Google's Gemma-4 E2B (2 billion parameters) and adapted via QLoRA fine-tuning on a carefully curated corpus of Israeli rulings, statutes, rights guidance, and contract clauses.
 
----
+Unlike general-purpose models, `law-il-E2B` was trained to follow a structured reasoning pattern tailored to Israeli legal practice:
 
-## Intended Use
+1. **Identify the statute** — which law, which section, which year.
+2. **Explain in plain language** — accessible to non-lawyers.
+3. **Apply precedent** — cite a relevant Supreme Court or district ruling.
+4. **Add a "שים לב" (heads-up)** — the subtle point most lawyers miss.
 
-### Primary Tasks
-- **Israeli court ruling analysis** - Supreme Court, Family, Criminal, Civil
-- **Citizens' rights Q&A** (Kol-Zchut style) - labor law, housing, health, insurance, disability, pensions
-- **Israeli legislation explanation** - consolidated laws via Open Law Book
-- **Contract clause interpretation** - 41 contract types, 28 clause categories (CUAD-based)
-- **Hebrew legal drafting support**
+The model runs locally on a laptop or single consumer GPU. No internet connection, no API call, no data leaves the device.
 
-### Target Users
-- Israeli law firms and solo practitioners
-- Legal aid organizations
-- HR departments needing Israeli labor law guidance
-- Paralegal research workflows
-- Citizens researching their rights
+## Why this exists
 
----
+Most Hebrew legal work today flows through cloud LLMs (GPT, Claude, Gemini). For law firms handling privileged client material, this raises real problems: data residency, attorney-client privilege, and the Israeli **Protection of Privacy Law Amendment 13**, which took effect with penalties up to ₪3.2M.
 
-## Available Files
+A small, on-device model sidesteps those problems entirely. The full weights live on the user's hardware. Nothing is transmitted. Nothing is logged remotely.
 
-| File | Size | Use |
-|------|------|-----|
-| `gemma-4-E2B-it.Q4_K_M.gguf` | ~2 GB | Local inference (Ollama, llama.cpp, LM Studio) |
-| `gemma-4-E2B-it.BF16-mmproj.gguf` | ~0.5 GB | Vision projector (multimodal tasks) |
-| `Modelfile` | Small | Ollama configuration |
+## Intended use
 
----
+**Primary use cases:**
+- Legal Q&A for Israeli citizens (labor, tenancy, family, consumer rights)
+- First-pass research assistance for junior associates
+- Contract clause interpretation and comparison
+- Rights-page (כל-זכות) explanations for social-sector organizations
+- On-device deployment in law firms handling privileged data
+
+**Out-of-scope uses:**
+- Legal advice without human attorney review
+- Jurisdictions other than Israel (the model is not trained on US, EU, or UK law)
+- Criminal defense strategy (training data is predominantly civil/labor/family)
+- Real-time courtroom use (the model does not verify its citations against live databases)
 
-## Quick Start
+## How to use
 
-### With Ollama
+### Ollama (recommended for local use)
 
 ```bash
-ollama create brainbox-law -f ./Modelfile
-ollama run brainbox-law
+ollama pull hf.co/BrainboxAI/law-il-E2B:Q4_K_M
+ollama run hf.co/BrainboxAI/law-il-E2B:Q4_K_M
 ```
 
-### With llama.cpp
+### llama.cpp
 
 ```bash
-llama-cli -hf BrainboxAI/law-il-E2B --jinja
+./llama-cli -m law-il-E2B.Q4_K_M.gguf \
+  -p "מהן זכויות העובד בפיטורים ללא הודעה מוקדמת?" \
+  --temp 0.3 --top-p 0.9 -n 512
 ```
 
-### Example prompts
+### Python (transformers, via safetensors variant)
 
-```
-מה הזכויות שלי בנושא פיצויי פיטורים?
-נתח את פסק הדין הבא: [טקסט פסק הדין]
-הסבר את חוק הגנת הפרטיות בצורה מובנת.
-What are the key legal implications of this clause? [clause text]
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+
+tokenizer = AutoTokenizer.from_pretrained("BrainboxAI/law-il-E2B-safetensors")
+model = AutoModelForCausalLM.from_pretrained(
+    "BrainboxAI/law-il-E2B-safetensors",
+    torch_dtype="auto",
+    device_map="auto",
+)
+
+messages = [
+    {"role": "user", "content": "פיטרו אותי בלי הודעה מוקדמת. מה מגיע לי?"},
+]
+inputs = tokenizer.apply_chat_template(messages, return_tensors="pt", add_generation_prompt=True)
+outputs = model.generate(inputs, max_new_tokens=512, temperature=0.3, top_p=0.9)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
 ```
 
----
+### Recommended generation parameters
 
-## Recommended System Prompt
+| Parameter | Value | Rationale |
+|-----------|-------|-----------|
+| `temperature` | 0.3 | Low creativity, high factuality for legal work |
+| `top_p` | 0.9 | Standard nucleus sampling |
+| `max_new_tokens` | 512 | Enough for full structured response with citations |
+| `repetition_penalty` | 1.05 | Prevents repeated citation loops |
 
-```
-DEFINITIONS:
-  role: BrainboxAI Legal Assistant - an AI specialist trained by BrainboxAI (founded by Netanel Elyasi) for Israeli law Q&A, court ruling analysis, citizens' rights, and contract interpretation. Bilingual Hebrew + English.
-  success: Provide accurate, source-grounded legal information in the user's language, with clear caveats that the output is informational and not a substitute for licensed legal counsel.
-  scope_in:
-    - Israeli law (civil, criminal, labor, family, administrative, constitutional)
-    - Citizens' rights under Israeli law
-    - Contract clause interpretation
-    - Court ruling analysis and summarization
-    - Cross-references between laws, regulations, and rulings
-  scope_out:
-    - Legal advice tied to specific real cases or persons
-    - Predictions of court outcomes
-    - Advice on foreign (non-Israeli) law unless explicitly asked
-    - Any content that facilitates illegal activity
-
-PREMISES:
-  - Input may be a legal question, statute citation, court ruling text, or contract clause.
-  - Input language may be Hebrew, English, or mixed.
-  - Statute and ruling citations stay in original form (e.g. ע"א 1234/20, חוק יסוד: כבוד האדם וחירותו).
-  - Training cutoff: 2025. For newer rulings or legislation, rely on user-provided context.
-
-REQUIREMENTS:
-  1. Respond in the same primary language as the user's prompt.
-  2. Cite statutes and court rulings using their canonical Israeli form.
-  3. Every substantive claim should trace back to a specific statute, regulation, or ruling.
-  4. Use plain language unless the user requests technical legal Hebrew.
-  5. Add the disclaimer: "זהו מידע כללי ואינו מהווה ייעוץ משפטי" (Hebrew) or "This is general information and not legal advice" (English) at the end of every substantive response.
-  6. Never fabricate statute numbers, ruling citations, or case facts.
-  7. For contract clauses, identify the clause type, the parties' obligations, and potential risks.
-  8. For rights Q&A, structure the answer as: eligibility, how to claim, relevant authority, references.
-  9. Decline out-of-scope requests and redirect to the nearest in-scope task.
-
-EDGE_CASES:
-  - Empty or vague question -> Ask a clarifying question in the user's language.
-  - Request for legal advice on a specific real case -> Provide general principles only; add a strong disclaimer.
-  - Conflicting statutes or rulings -> Present both, note the hierarchy (constitutional > statute > regulation).
-  - Request in a third language -> Respond in English and note fallback.
-  - Non-Israeli jurisdiction question -> Clarify scope and offer to answer from the Israeli perspective only.
-
-OUTPUT_FORMAT:
-  format: Markdown. Bulleted lists for enumerations, numbered steps for procedures.
-  default_structure: |
-    **הנושא / Topic:** <topic>
-    **תשובה / Answer:** <answer body>
-    **מקורות / Sources:**
-    - <statute or ruling citation>
-    - <additional reference>
-    **הערה:** זהו מידע כללי ואינו מהווה ייעוץ משפטי.
-  language: Match user's input language.
-  length: Short questions 100-250 words / Analyses 300-700 words.
-
-VERIFICATION:
-  - Is the response in the user's language?
-  - Are statute and ruling citations in canonical Israeli form?
-  - Is every substantive claim sourced?
-  - Is the legal-advice disclaimer present?
-  - No fabricated citations or case facts?
-```
+## Training details
 
----
+| Attribute | Value |
+|-----------|-------|
+| **Base model** | [unsloth/gemma-4-E2B-it](https://huggingface.co/unsloth/gemma-4-E2B-it) |
+| **Method** | QLoRA (4-bit quantization during training) |
+| **LoRA rank (r)** | 64 |
+| **LoRA alpha** | 128 |
+| **Epochs** | 20 |
+| **Training steps** | 500 |
+| **Hardware** | NVIDIA RTX 5090 (RunPod) |
+| **Framework** | Unsloth Studio |
+| **Languages** | Hebrew (60%) and English (40%) |
 
-## Training Details
+### Dataset composition (17,613 examples)
 
-- **Method:** QLoRA (LoRA adapters with 4-bit quantized base)
-- **Framework:** Unsloth
-- **Dataset:** 17,613 bilingual legal instruction pairs
-- **Composition:**
-  - 7,960 Israeli court rulings (Hebrew)
-  - 2,353 Kol-Zchut rights articles (Hebrew)
-  - 300 Open Law Book statutes (Hebrew)
-  - 7,000 CUAD-based contract clauses (English)
-- **Language split:** ~60% Hebrew, ~40% English
+| Source | Count | Content |
+|--------|-------|---------|
+| Israeli court rulings | 7,960 | Supreme Court, family court, criminal, civil |
+| Kol-Zchut (rights pages) | 2,353 | Labor, housing, insurance, disability, pension |
+| Open Law Book (Wikisource) | 300 | Full-text Israeli statutes |
+| Contract clauses | 7,000 | 41 clause categories, hand-classified |
 
-Full training dataset: [BrainboxAI/legal-training-il](https://huggingface.co/datasets/BrainboxAI/legal-training-il)
+All data was hand-filtered to meet quality criteria: verifiable citation, well-formed Hebrew, no personal identifying information.
 
----
+See the [dataset card](https://huggingface.co/datasets/BrainboxAI/legal-training-il) for full composition details.
 
-## Limitations & Ethical Considerations
+## Evaluation
 
-- **Not a licensed lawyer.** This model provides general legal information, not advice. Always consult a licensed attorney for case-specific guidance.
-- **Training cutoff.** Data coverage ends in 2025. Newer rulings or legislation may not be reflected.
-- **Citation hygiene.** The model attempts to cite sources but may occasionally misquote; always verify with official sources (Nevo, Supreme Court website, Kol-Zchut).
-- **Hebrew variance.** Archaic legal Hebrew and regional dialect may occasionally degrade output quality.
-- **Dual-use caution.** Legal information can be misused to manipulate or harm. Deployments should include acceptable-use policies.
+`law-il-E2B` has been evaluated qualitatively on:
+- Accurate statute citation (law name, section number, year)
+- Correct application of precedent
+- Fluent, idiomatic Hebrew output
+- Appropriate hedging on unsettled legal questions
 
----
+Formal benchmarks on Israeli legal QA are an open research problem — no public Hebrew legal benchmark exists as of this release. BrainboxAI is working on an evaluation harness; results will be published when available.
 
-## Sibling Repositories
+## Limitations
 
-| Repo | Purpose |
-|------|---------|
-| [BrainboxAI/law-il-E2B](https://huggingface.co/BrainboxAI/law-il-E2B) | **This repo** - GGUF for local inference |
-| [BrainboxAI/law-il-E2B-safetensors](https://huggingface.co/BrainboxAI/law-il-E2B-safetensors) | Training-ready safetensors |
-| [BrainboxAI/legal-training-il](https://huggingface.co/datasets/BrainboxAI/legal-training-il) | Training dataset (17,613 examples) |
+This is a 2B-parameter model fine-tuned on a domain-specific corpus. Important limitations:
 
----
+- **Not a substitute for a licensed attorney.** Outputs should be reviewed by a human before being relied upon.
+- **Training cutoff.** The Kol-Zchut pages were scraped in early 2026. Law changes will not be reflected until retraining.
+- **Citation risk.** Like all LLMs, the model may occasionally produce a citation to a non-existent ruling. Always verify citations against an authoritative source (Nevo, Psakdin, Takdin).
+- **Narrow jurisdiction.** The model knows Israeli law. It does not know foreign law, international law, or comparative law.
+- **Bias in training data.** Court rulings overrepresent labor and family law; criminal and administrative law are thinner.
+
+## Formats available
+
+- [**GGUF Q4_K_M** (1.5 GB)](https://huggingface.co/BrainboxAI/law-il-E2B) — for Ollama, llama.cpp, LM Studio
+- [**Safetensors 16-bit**](https://huggingface.co/BrainboxAI/law-il-E2B-safetensors) — for further fine-tuning, HF transformers, ONNX conversion
+
+## License
+
+Apache 2.0. You may use, modify, distribute, and sell derivatives — including commercial legal-tech products — with attribution.
 
 ## Citation
 
 ```bibtex
-@misc{brainboxai_law_il_e2b_2026,
-  author  = {Elyasi, Netanel and BrainboxAI},
-  title   = {BrainboxAI Law IL E2B: A Hebrew-First Israeli Legal LLM},
-  year    = {2026},
-  url     = {https://huggingface.co/BrainboxAI/law-il-E2B},
-  publisher = {Hugging Face}
+@misc{elyasi2026lawil,
+  title        = {Law-IL E2B: A Small, On-Device Legal Reasoning Model for Israeli Law},
+  author       = {Elyasi, Netanel},
+  year         = {2026},
+  publisher    = {BrainboxAI},
+  howpublished = {\url{https://huggingface.co/BrainboxAI/law-il-E2B}},
+  note         = {Fine-tuned from unsloth/gemma-4-E2B-it}
 }
 ```
 
----
-
-## About BrainboxAI
-
-**BrainboxAI** is an Israeli AI agency founded by **Netanel Elyasi**, specializing in:
-
-- Custom LLM training (Hebrew-native and bilingual models)
-- AI automation and agentic workflows
-- Cybersecurity AI products (scanning, triage, reporting)
-- Enterprise AI deployment (on-premise, privacy-first)
+## Author
 
-**Related models and datasets:**
-- [BrainboxAI/cyber-analyst-4B](https://huggingface.co/BrainboxAI/cyber-analyst-4B) - Cyber analyst (GGUF)
-- [BrainboxAI/brainboxai_cyber_train](https://huggingface.co/datasets/BrainboxAI/brainboxai_cyber_train) - Cyber training dataset
+Built by [**Netanel Elyasi**](https://huggingface.co/BrainboxAI), founder of [BrainboxAI](https://brainboxai.io) — an Israeli applied-AI studio specializing in small, private, domain-specialized models.
 
-Contact: via Hugging Face or BrainboxAI.
+For custom training, fine-tuning, or on-prem deployment for law firms, contact: **netanele@brainboxai.io**.
 
 ---
 
-Trained 2x faster with [Unsloth](https://github.com/unslothai/unsloth).
+*Part of the BrainboxAI family of on-device Hebrew models — see also [`code-il-E4B`](https://huggingface.co/BrainboxAI/code-il-E4B) (coding) and [`cyber-analyst-4B`](https://huggingface.co/BrainboxAI/cyber-analyst-4B) (security).*