Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,90 @@
+---
+license: apache-2.0
+language:
+- ar
+pipeline_tag: text-generation
+tags:
+- gguf
+- llama-cpp
+- egyptian-arabic
+- conversational
+- cpu
+base_model: Qwen/Qwen2.5-1.5B-Instruct
+---
+
+# Mini-NABD — lightweight Egyptian-Arabic chat model (GGUF)
+
+Mini-NABD is a tiny conversational model that speaks Egyptian Arabic (Masri)
+like a friend: casual, funny when natural, short answers. It is an **additional**
+fast/local companion to the main NABD AI, not a replacement.
+
+## Files
+
+| file | what | size | RAM |
+|---|---|---|---|
+| `mini-nabd-q4_k_m.gguf` | recommended 4-bit | ~1.0 GB | ~2 GB |
+
+Only the smallest practical file is published — no variant zoo.
+
+## Run it (CPU, 4GB RAM, no GPU)
+
+```bash
+# llama.cpp server (OpenAI-compatible)
+./llama-server -m mini-nabd-q4_k_m.gguf -c 2048 --port 11435
+
+curl http://127.0.0.1:11435/v1/chat/completions -H 'Content-Type: application/json' -d '{
+  "model": "mini-nabd",
+  "messages": [
+    {"role": "system", "content": "أنت نبض الصغير — صاحب مصري خفيف الدم، رد بالعامية مختصر."},
+    {"role": "user", "content": "عامل ايه؟"}
+  ]}'
+```
+
+Or Python: `pip install llama-cpp-python`, then `Llama("mini-nabd-q4_k_m.gguf", n_ctx=2048)`.
+
+- Recommended context: **2048** (fits 4GB with room to spare).
+- Startup: seconds. Speed on a normal laptop CPU: roughly 15–40 tok/s
+  (measured numbers go in the release notes per build).
+- Temp 0.7, max ~256 tokens — it is tuned for short replies.
+
+## NABD integration + Tavily example
+
+```js
+const { autoProvider, needsSearch } = require('./router'); // providers/router
+const { tavilySearch, formatForMini } = require('./tavily'); // providers/tavily
+
+async function answer(userText) {
+  let context = '';
+  if (needsSearch(userText)) {           // router decides, not the tiny model
+    const t = await tavilySearch(userText);   // TAVILY_API_KEY stays server-side
+    context = formatForMini(userText, t) + '\n';
+  }
+  const sys = 'أنت نبض الصغير — صاحب مصري خفيف الدم، رد بالعامية مختصر.'
+    + (context ? '\n' + context : '');
+  return miniReply(sys, userText);        // POST to 127.0.0.1:11435, fallback main
+}
+```
+
+## Training (v0 status: base + system prompt)
+
+v0 ships `Qwen2.5-1.5B-Instruct` Q4_K_M unchanged — the Egyptian personality
+comes from the system prompt in `SYSTEM.md`, not from weights yet. Measured
+gaps on the raw base (Arabizi loops, MSA-style refusals of light slang) are
+documented and are exactly what v1 fixes.
+
+v1 roadmap (ready to run, see `training/`): LoRA r=16 on 60 hand-written
+Egyptian pairs (greetings, slang, Arabizi, humor, live-info refusals) on a
+Colab T4, merge + Q4_K_M export replacing this file. Tool routing stays
+external, so weights will contain zero tool tokens.
+
+## Limitations
+
+- Small talk + simple explanations only — hard reasoning, long code, and
+  vision go to the main AI.
+- Knowledge cutoff = base model; live facts need Tavily via the router.
+- Egyptian dialect is a style layer over Qwen's Arabic — MSA slips through
+  on technical topics.
+
+## License
+
+Apache-2.0 (inherits Qwen2.5 + Llama.cpp ecosystem licensing for the base).