card: loopl 2B v1.1 (bf16) — train/cards.py

README.md

@@ -20,24 +20,35 @@ tags:
 - vision
 - image-text-to-text
 ---
+<p align="center">
+  <a href="https://loopl.dev"><img src="https://huggingface.co/cagataydev/loopl-2b/resolve/main/assets/banner.png" alt="loopl — Agents that run on your phone." width="100%"></a>
+</p>
+
+<div align="center" style="display:flex;flex-wrap:wrap;gap:6px;justify-content:center"><a href="https://huggingface.co/cagataydev/loopl-2b/blob/main/README.md#license"><img alt="license: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-5d5d63?style=flat-square&labelColor=0b0b0c"></a> <img alt="bf16: transformers · 4.43 GB" src="https://img.shields.io/badge/bf16-transformers%20%C2%B7%204.43%20GB-5d5d63?style=flat-square&labelColor=0b0b0c"> <img alt="vision: ✓ 297 tensors kept" src="https://img.shields.io/badge/vision-%E2%9C%93%20297%20tensors%20kept-5d5d63?style=flat-square&labelColor=0b0b0c"> <img alt="tool calling: native + loopl JSON" src="https://img.shields.io/badge/tool%20calling-native%20%2B%20loopl%20JSON-5d5d63?style=flat-square&labelColor=0b0b0c"> <img alt="params: 2B" src="https://img.shields.io/badge/params-2B-5d5d63?style=flat-square&labelColor=0b0b0c"> <img alt="version: v1.1" src="https://img.shields.io/badge/version-v1.1-5d5d63?style=flat-square&labelColor=0b0b0c"> <a href="https://testflight.apple.com/join/uUNjfzW9"><img alt="Get it on: TestFlight" src="https://img.shields.io/badge/Get%20it%20on-TestFlight-ff5a1f?style=flat-square&labelColor=0b0b0c&logo=apple&logoColor=white"></a> <a href="https://loopl.dev"><img alt="site: loopl.dev" src="https://img.shields.io/badge/site-loopl.dev-c2410c?style=flat-square&labelColor=0b0b0c"></a> <a href="https://huggingface.co/collections/cagataydev/loopl-on-device-agents-swift-6ac51395b13a9c41d4932eaf"><img alt="collection: 6 models" src="https://img.shields.io/badge/collection-6%20models-c2410c?style=flat-square&labelColor=0b0b0c"></a></div>
+
 # loopl 2B · v1.1
 
-**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)
-· the models: [the loopl collection](https://huggingface.co/collections/cagataydev/loopl-on-device-agents-swift-6ac51395b13a9c41d4932eaf).
+**An agent that lives on your phone.** loopl runs the model, the loop and the tools on the device. It talks, uses the
+phone, asks before it acts — and works with the network off. This repo is the merged bf16 weights — **the base for *Train your own*** — of the
+2B loopl model, a Qwen3.5 post-tuned to run loopl's agent loop well, know who it is, and read images.
+
+<table align="center"><tr><td align="center" width="33%"><img src="https://huggingface.co/cagataydev/loopl-2b/resolve/main/assets/see-tool.png" alt="It uses the phone — every tool call is a row." width="250"></td><td align="center" width="33%"><img src="https://huggingface.co/cagataydev/loopl-2b/resolve/main/assets/see-approval.png" alt="It asks before anything leaves the device." width="250"></td><td align="center" width="33%"><img src="https://huggingface.co/cagataydev/loopl-2b/resolve/main/assets/see-vision.png" alt="Show it a photo. It reads it on-device." width="250"></td></tr><tr><td align="center"><sub>It uses the phone — every tool call is a row.</sub></td><td align="center"><sub>It asks before anything leaves the device.</sub></td><td align="center"><sub>Show it a photo. It reads it on-device.</sub></td></tr></table>
+<p align="center"><sub>Real captures from the free iPhone app.</sub></p>
+
+## What loopl is
 
-**This model** is [Qwen/Qwen3.5-2B](https://huggingface.co/Qwen/Qwen3.5-2B) fully fine-tuned by Cagatay Cali
-([@cagataycali](https://github.com/cagataycali)) on [cagataydev/loopl-train](https://huggingface.co/datasets/cagataydev/loopl-train) *(private)*: 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.
+- **A Swift SDK** — `Agent(model:tools:)` and a small, honest loop: model → tools → model until it answers. Tool errors go
+  back to the model (it fixes the call instead of repeating it); anything that leaves the device waits for a tap.
+  Runtimes for MLX, llama.cpp and Apple's on-device model; hooks, checkpoints, structured output, tracing.
+- **A free iPhone app** built on it — pick a model, talk to it in airplane mode, let it use the phone (torch, haptics,
+  translation, speech, image generation, other apps, memory, HTTP), show it photos, record a take, and **train it on your
+  own conversations** from the phone. No account, nothing collected.
+- **These models** — the same Qwen3.5 the app offers, post-tuned so the loop, the identity and the tool manners are in the
+  weights, not in a system prompt you cannot see.
 
-> **This repo is the merged bf16 checkpoint** (`Qwen3_5ForConditionalGeneration`, vision included) — **use it as the base for continual post-tuning in loopl** (Models › Train your own, or `train/loopl_sft.py --base cagataydev/loopl-2b`): every round starts from bf16, never from 4-bit weights. Ready-to-run exports: [mlx](https://huggingface.co/cagataydev/loopl-2b-4bit) · [gguf](https://huggingface.co/cagataydev/loopl-2b-GGUF) *(private)*.
+[loopl.dev](https://loopl.dev) · [Get it on TestFlight](https://testflight.apple.com/join/uUNjfzW9) · [github.com/cagataycali/loopl](https://github.com/cagataycali/loopl)
 
-## Scores
+## This model
 
 | probe | this model | previous (v1) | base Qwen3.5 4-bit |
 |---|---:|---:|---:|
@@ -50,6 +61,8 @@ Qwen3.5 does.
 
 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.
 
+Vision: the base's tower is frozen and **kept** — 297 `vision_tower.*` tensors in the MLX export, so the app shows the photo button.
+
 ## Use it today
 
 **In the loopl app (iPhone).** Install from [TestFlight](https://testflight.apple.com/join/uUNjfzW9) → Models → the **loopl models** section lists this
@@ -67,18 +80,31 @@ python -m mlx_vlm.generate --model cagataydev/loopl-2b-4bit \
 **With llama.cpp:** the GGUF Q4_K_M export (`cagataydev/loopl-2b-GGUF`) is not public yet; export your own from the bf16 weights with
 llama.cpp's `convert_hf_to_gguf.py --no-mtp` (text only — the converter has no vision path).
 
-**From Swift with the loopl SDK** (`https://github.com/cagataycali/loopl`, products `Loopl` + `LooplRuntimes`):
+**From Swift with the loopl SDK** — the snippet below is `docs/start.md` § "Run the loop" in [the loopl repo](https://github.com/cagataycali/loopl),
+compile-checked in CI against the package (products `Loopl` + `LooplRuntimes`); `spec` is this repo's `ModelSpec` and `dir` the
+downloaded folder:
 
 ```swift
 import Loopl
 import LooplRuntimes
-
-let model = MLXModel()                                     // or GGUFModel() for a GGUF export
-try await model.load(spec, from: weightsDirectory) { _ in } // spec: the ModelSpec for cagataydev/loopl-2b-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: "") }
+import Foundation
+
+func chat(_ spec: ModelSpec, at dir: URL) async throws {
+    let model = MLXModel()                                       // Metal — a real device
+    try await model.load(spec, from: dir) { _ in }
+
+    let agent = Agent(model: model,
+                      tools: [CurrentTimeTool(), CalculatorTool()],
+                      systemPrompt: "You are a concise assistant on the user's phone.")
+
+    for try await event in agent.stream("What time is it in Istanbul, and what is 23 × 47?") {
+        switch event {
+        case .text(let t):            print(t, terminator: "")
+        case .toolStarted(let use):   print("\n→ \(use.name)")
+        case .toolResult(let r):      print("← \(r.content)")
+        default: break
+        }
+    }
 }
 ```
 
@@ -124,3 +150,24 @@ addresses — see the dataset card. No user conversations from the app are in th
 ## License
 
 Apache-2.0, inherited from the Qwen3.5 base. The fine-tune, exports and dataset are © Cagatay Cali, same license.
+
+## The family
+
+Six public repos, one recipe. The app lists the three MLX rows under **Models › loopl models** (2B is the sweet spot for speed on an
+iPhone 15/16; 4B is the most knowledgeable; 0.8B fits anywhere). Every bf16 repo is a valid `--base` for the next round.
+
+| | MLX 4-bit · vision · what the app downloads | bf16 · the base to keep training |
+|---|---|---|
+| **0.8B** | [`cagataydev/loopl-0.8b-4bit`](https://huggingface.co/cagataydev/loopl-0.8b-4bit) · 625 MB | [`cagataydev/loopl-0.8b`](https://huggingface.co/cagataydev/loopl-0.8b) · 1.71 GB |
+| **2B** | [`cagataydev/loopl-2b-4bit`](https://huggingface.co/cagataydev/loopl-2b-4bit) · 1.72 GB | [`cagataydev/loopl-2b`](https://huggingface.co/cagataydev/loopl-2b) · 4.43 GB ← this repo |
+| **4B** | [`cagataydev/loopl-4b-4bit`](https://huggingface.co/cagataydev/loopl-4b-4bit) · 3.03 GB | [`cagataydev/loopl-4b`](https://huggingface.co/cagataydev/loopl-4b) · 9.08 GB |
+
+All of them: [the loopl collection](https://huggingface.co/collections/cagataydev/loopl-on-device-agents-swift-6ac51395b13a9c41d4932eaf).
+
+## Links
+
+- Site and docs — [loopl.dev](https://loopl.dev) · SDK: [agent loop](https://loopl.dev/sdk/agent/), [tools](https://loopl.dev/sdk/tools/), [human in the loop](https://loopl.dev/sdk/hitl/), [models](https://loopl.dev/models/)
+- App — [Get it on TestFlight](https://testflight.apple.com/join/uUNjfzW9) (iOS 18+, free, public beta)
+- Code — [github.com/cagataycali/loopl](https://github.com/cagataycali/loopl) · [issues](https://github.com/cagataycali/loopl/issues) · training: [github.com/cagataycali/loopl-train](https://github.com/cagataycali/loopl-train)
+- Models — [the loopl collection](https://huggingface.co/collections/cagataydev/loopl-on-device-agents-swift-6ac51395b13a9c41d4932eaf) · data: [cagataydev/loopl-train](https://huggingface.co/datasets/cagataydev/loopl-train) *(private)*
+- Built by Cagatay Cali — [@cagataycali](https://github.com/cagataycali)