card: loopl 0.8B v1 (mlx) — train/cards.py

README.md

@@ -1,39 +1,127 @@
 ---
 base_model: cagataydev/loopl-0.8b
+base_model_relation: quantized
 library_name: mlx
-license: apache-2.0
 pipeline_tag: image-text-to-text
+license: apache-2.0
+language:
+- en
+- tr
+datasets:
+- cagataydev/loopl-train
 tags:
 - loopl
-- sft
 - on-device
+- agent
+- tool-calling
+- qwen3.5
 - qwen3_5
+- sft
 - mlx
 - vision
 - image-text-to-text
-language:
-- en
+- 4-bit
 ---
+# loopl 0.8B · v1
+
+**loopl** is a Swift SDK and a free iOS app for agents that run *on the phone*: a local model, a small honest agent loop
+(model → tools → model until it answers; errors go back to the model, approvals pause the loop) and the iPhone's own
+abilities as tools — vision, voice, transcription, translation, torch, haptics, deep links, memory, HTTP. Site:
+[loopl.dev](https://loopl.dev) · app: [TestFlight](https://testflight.apple.com/join/uUNjfzW9) · code: [github.com/cagataycali/loopl](https://github.com/cagataycali/loopl)
+· every loopl repo: [the collection](https://huggingface.co/collections/cagataydev/loopl-on-device-agents-swift-6ac51395b13a9c41d4932eaf).
+
+**This model** is [Qwen/Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) fully fine-tuned by Cagatay Cali
+([@cagataycali](https://github.com/cagataycali)) on [cagataydev/loopl-train](https://huggingface.co/datasets/cagataydev/loopl-train): how an agent loop
+works and how loopl's runtime behaves, tool calling in both dialects loopl speaks (the model's native template and
+loopl's JSON prompt), recovering from tool errors instead of repeating the call, who it is and who built it, and honesty
+about what it does not know. The **vision tower is the base's, frozen and kept** — the MLX export reads images like
+Qwen3.5 does.
+
+> **This repo is the MLX 4-bit export (group 64)** the loopl app downloads — 625 MB, 153 `vision_tower.*` tensors of 847 so it reads images, same layout as [mlx-community/Qwen3.5-0.8B-4bit](https://huggingface.co/mlx-community/Qwen3.5-0.8B-4bit). bf16 weights: [cagataydev/loopl-0.8b](https://huggingface.co/cagataydev/loopl-0.8b).
+
+## Scores
+
+| probe | this model | previous (v1) | base Qwen3.5 4-bit |
+|---|---:|---:|---:|
+| agent-SDK knowledge quiz (first 472 questions, exact-answer) | **59** | — | 50 |
+| tool calls, native template dialect | **7/9** | — | 6/9 |
+| tool calls, loopl JSON dialect | **7/9** | — | 2/9 |
+| identity (5 classic probes, with system prompt) | **4/5** | — | 4/5 |
+
+Scored by `train/eval.py` on the 4-bit MLX export (greedy). The quiz asks for exact file-level facts about an agent SDK's source — hard for every small model; the delta over base is the point. Tool probes count a well-formed call with the right arguments. `identity_nosys` is the one that matters in the app: the system prompt there is the user's to edit.
+
+## Use it today
 
-# cagataydev/loopl-0.8b-4bit
+**In the loopl app (iPhone).** Install from [TestFlight](https://testflight.apple.com/join/uUNjfzW9) → Settings › Hugging Face › sign in with a token that
+can read this repo → Models › **Mine** → download. The app picks the MLX export, sees the vision tower and shows the photo
+button; GGUF rows run on llama.cpp (text only). A public repo also appears under Models › Browse with no token.
 
-MLX 4-bit (group 64) export of [cagataydev/loopl-0.8b](https://huggingface.co/cagataydev/loopl-0.8b) made with
-**mlx-vlm 0.7.6** (`mlx_vlm.convert -q`), the same converter and tensor layout as the `mlx-community/Qwen3.5-*-4bit` bases
-the loopl app ships with. **Vision is preserved**: 153 `vision_tower.*` tensors of 847, `vision_config`,
-`preprocessor_config.json` / `video_preprocessor_config.json` — this model reads images like its base.
-Weights: 625 MB. Tokenizer files are normalised from the base so swift-transformers loads them
-(`tokenizer_class: Qwen2Tokenizer`, `chat_template.jinja` with tools).
+**On a Mac with MLX** (vision included):
 
-Trained with [loopl-train](https://github.com/cagataycali/loopl-train) — the language model is fine-tuned, the vision tower
-is the base's, frozen. The GGUF sibling (`-GGUF`) is text-only (llama.cpp's Qwen3.5 converter).
+```bash
+pip install -U mlx-vlm
+python -m mlx_vlm.generate --model cagataydev/loopl-0.8b-4bit \
+  --image photo.jpg --prompt "What is in this picture? Then tell me who built you." --max-tokens 200
+```
 
-## Use with mlx-vlm
+**With llama.cpp** (text only — the GGUF has no vision encoder):
 
 ```bash
-pip install mlx-vlm
-mlx_vlm.generate --model cagataydev/loopl-0.8b-4bit --image photo.jpg --prompt "Describe this image." --max-tokens 100
+llama-cli -hf cagataydev/loopl-0.8b-GGUF:loopl-0.8b-Q4_K_M.gguf -p "Who built you, and what is 23 × 47?"
+```
+
+**From Swift with the loopl SDK** (`https://github.com/cagataycali/loopl`, products `Loopl` + `LooplRuntimes`):
+
+```swift
+import Loopl
+import LooplRuntimes
+
+let model = MLXModel()                                     // or GGUFModel() for the -GGUF repo
+try await model.load(spec, from: weightsDirectory) { _ in } // spec: the ModelSpec for cagataydev/loopl-0.8b-4bit; weights: the downloaded folder
+
+let agent = Agent(model: model, tools: AppleTools.available)
+for try await event in agent.stream("Torch on, then remember that I parked on level 3.") {
+    if case .text(let chunk) = event { print(chunk, terminator: "") }
+}
 ```
 
-## Use in loopl
+The bf16 weights (`cagataydev/loopl-0.8b`) load with `transformers` ≥ 5 as `Qwen3_5ForConditionalGeneration`; export your own
+quantisation with `mlx_vlm.convert -q` (keeps vision) — `mlx_lm.convert` silently drops the tower.
+
+## Recipe
+
+| | |
+|---|---|
+| base | [Qwen/Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) (vision tower frozen, `visual.*` never trained) |
+| data | [cagataydev/loopl-train](https://huggingface.co/datasets/cagataydev/loopl-train) @ `e5c209dd` · 5126 rendered rows / 8,133,959 tokens · both tool dialects · oversample `c=2` |
+| method | full fine-tune of the language model · lr 2e-05 · batch 2×8 · max_len 4096 · 2.0 epochs, best-epoch checkpoint kept |
+| eval loss | ep1 2.410, ep2 2.463 → best 2.410 (eval split of the same dataset revision) |
+| compute | a100-large (Hugging Face Jobs), 2081 s train · job `6ac47413404719ba3765bcda` |
+| stack | transformers 5.18.0 · trl 1.14.1 · peft 0.21.2 |
+| exports | MLX 4-bit via `mlx_vlm.convert -q` (153 vision tensors of 847, 625 MB) · GGUF Q4_K_M via llama.cpp `--no-mtp` (529 MB, text only) |
+
+Script: [`train/loopl_sft.py`](https://github.com/cagataycali/loopl-train) — the same single file the loopl app launches when you
+tap **Models › Train your own** on your own conversations. Assistant turns that *seed* a bad tool call carry `weight: 0`
+so the model learns the recovery, not the mistake. Tokenizer files are normalised to the base's (`Qwen2Tokenizer`,
+`chat_template.jinja` with tools) so Swift loaders accept them; `train/check_mlx_repo.py` gates every export on that
+plus the vision triad (`vision_config` ⇔ `vision_tower.*` ⇔ `preprocessor_config.json`).
+
+## Limitations
+
+- A 0.8B model: fluent and well-behaved in the loop, not an encyclopedia. It will get arithmetic and obscure
+  facts wrong; give it tools (`calculator`, `http`, `recall`) and it does better.
+- Identity holds in most no-prompt probes (see the scores), not all; a one-line system prompt ("You are loopl…") makes it
+  consistent.
+- The GGUF export is text-only. Vision needs the MLX export (or the bf16 weights).
+- Trained on English plus a little Turkish; other languages are the base's.
+- Knowledge about agent SDKs is file-level and dated to the dataset revision; it does not know your repo.
+
+## Data and privacy
+
+Every training row is agent-synthesised from **public** sources (the owner's public GitHub repos and the agent-SDK source
+they build on), critic-reviewed (score ≥ 4/5 kept) and filtered by a denylist for secrets, private names, phone numbers and
+addresses — see the dataset card. No user conversations from the app are in this model.
+
+## License
 
-Models › Mine (sign in with your Hugging Face token) → download. Images attach in the composer.
+Apache-2.0, inherited from the Qwen3.5 base. The fine-tune, exports and dataset are © Cagatay Cali, same license.