release: flowcast-v4-lite — 809MB stack, 100% benchmarks, IR v5 push5

README.md

@@ -0,0 +1,135 @@
+---
+license: apache-2.0
+base_model:
+  - mlx-community/LFM2.5-1.2B-Instruct-4bit
+  - mlx-community/functiongemma-270m-it-4bit
+tags:
+  - mlx
+  - lfm2
+  - functiongemma
+  - lora
+  - voice-agent
+  - desktop-automation
+  - computer-use
+  - flowcast
+  - gemmaflow
+  - apple-silicon
+  - compact-ir
+library_name: mlx-lm
+pipeline_tag: text-generation
+---
+
+# flowcast-v4-lite · sub-1GB voice agent stack
+
+**Flowcast v4-lite** is an **809 MB** hot-path stack for macOS voice agents. It builds on [`flowcast-v3-lite`](https://huggingface.co/nsalerni/flowcast-v3-lite) with a promoted LFM2.5 writer, IR v5 push5 planner, transcript-first automation repairs, and intent fast-path routing.
+
+> *100% benchmark accuracy. Faster dictation. IR v5 fallback when repairs miss.*
+
+## Benchmarks (vs v3-lite)
+
+| Gate | v3-lite | v4-lite | Δ |
+|------|---------|---------|---|
+| Core overall | 100% | **100%** | tie |
+| Expanded overall | 100% | **100%** | tie |
+| Held-out overall | 100% | **100%** | tie |
+| Dictation p50 | 360 ms | **208 ms** | **-152 ms** |
+| Core avg latency | 116 ms | **78 ms** | **-38 ms** |
+| IR model path p50 | 793 ms | **453 ms** | **-340 ms** |
+| Hot download | ~809 MB | **~809 MB** | same |
+
+Production automation resolves via deterministic transcript repairs and intent fast-path (0 IR calls on the hot path). IR v5 is exercised on the fallback model path.
+
+## Architecture
+
+```
+spoken command
+    → transcript-first repairs + intent fast-path  (dominant, ~0 ms)
+    → FunctionGemma IR v5  (~270M + 5MB adapter, fallback)
+    → compact JSON intent
+    → transcript-aware compiler
+    → DesktopAutomationPlan JSON
+
+spoken dictation / intent
+    → LFM2.5 writer  (~1.2B + 42MB adapter, KV-cached prefix)
+    → polished text or intent label
+```
+
+## Quick start
+
+```bash
+pip install mlx-lm huggingface_hub gemmaflow-tune
+```
+
+```python
+from huggingface_hub import snapshot_download
+from mlx_lm import load, generate
+from gemmaflow_tune.compact_ir import compact_ir_prompt, parse_compact_ir, repair_compact_ir, compile_compact_ir
+
+bundle = snapshot_download("nsalerni/flowcast-v4-lite")
+writer_base = snapshot_download("mlx-community/LFM2.5-1.2B-Instruct-4bit")
+ir_base = snapshot_download("mlx-community/functiongemma-270m-it-4bit")
+
+writer_model, writer_tok = load(writer_base, adapter_path=f"{bundle}/writer")
+ir_model, ir_tok = load(ir_base, adapter_path=f"{bundle}/ir")
+
+# Automation: IR → compiler (fallback path)
+transcript = "open codex and create a new thread in my loudink project"
+ir_prompt = compact_ir_prompt(transcript)
+ir_out = generate(ir_model, ir_tok, prompt=ir_prompt, max_tokens=96)
+ir = repair_compact_ir(parse_compact_ir(ir_out), transcript)
+plan = compile_compact_ir(ir, transcript=transcript)
+print(plan)
+```
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `writer/adapters.safetensors` | LFM2.5 writer LoRA (`promoted_core_100`) |
+| `writer/adapter_config.json` | Writer LoRA config |
+| `ir/adapters.safetensors` | FunctionGemma IR v5 push5 LoRA |
+| `ir/adapter_config.json` | IR LoRA config |
+| `inference_config.json` | Runtime settings + benchmark scores |
+| `manifest.json` | Production manifest for GemmaFlow integration |
+
+## Recommended inference settings
+
+```json
+{
+  "runner_kind": "compact_ir",
+  "prompt_mode": "verbose",
+  "json_early_stop": true,
+  "writer_use_prompt_kv_cache": true,
+  "ir_use_prompt_kv_cache": true,
+  "transcript_first_ir": true,
+  "intent_fast_path": true,
+  "temperature": 0.0,
+  "top_p": 1.0,
+  "ir_max_tokens": 96,
+  "dictation_max_tokens": 192
+}
+```
+
+## Training lineage
+
+Fine-tuned with [gemmaflow-tune](https://github.com/nsalerni/finetune-rl-gemma):
+
+- Writer base: `mlx-community/LFM2.5-1.2B-Instruct-4bit`
+- IR base: `mlx-community/functiongemma-270m-it-4bit`
+- Method: LoRA on both models + deterministic transcript compiler + push5 IR corpus
+- Predecessor: [`nsalerni/flowcast-v3-lite`](https://huggingface.co/nsalerni/flowcast-v3-lite)
+
+## Citation
+
+```bibtex
+@misc{flowcastv4lite2026,
+  title  = {flowcast-v4-lite: Sub-1GB Voice Desktop Automation for GemmaFlow},
+  author = {Salerni, Nicola},
+  year   = {2026},
+  url    = {https://huggingface.co/nsalerni/flowcast-v4-lite}
+}
+```
+
+## License
+
+Apache 2.0. Base models subject to their respective licenses (LFM2.5, FunctionGemma/Gemma).

inference_config.json

@@ -0,0 +1,40 @@
+{
+  "model_name": "flowcast-v4-lite",
+  "model_tag": "flowcast-v4-lite",
+  "runner_kind": "compact_ir",
+  "hf_repo": "nsalerni/flowcast-v4-lite",
+  "predecessor": "nsalerni/flowcast-v3-lite",
+  "writer_base_model": "mlx-community/LFM2.5-1.2B-Instruct-4bit",
+  "ir_base_model": "mlx-community/functiongemma-270m-it-4bit",
+  "writer_adapter_path": "writer",
+  "ir_adapter_path": "ir",
+  "writer_checkpoint": "adapters.safetensors",
+  "writer_use_prompt_kv_cache": true,
+  "ir_checkpoint": "adapters.safetensors",
+  "ir_use_prompt_kv_cache": true,
+  "transcript_first_ir": true,
+  "intent_fast_path": true,
+  "prompt_mode": "verbose",
+  "json_early_stop": true,
+  "heavy_fallback": false,
+  "ir_max_tokens": 96,
+  "download_mb": 809,
+  "benchmarks": {
+    "core_overall": 1.0,
+    "expanded_overall": 1.0,
+    "held_out_overall": 1.0,
+    "core_automation": 1.0,
+    "core_web_routing": 1.0,
+    "core_generalization": 1.0,
+    "core_intent": 1.0,
+    "core_dictation": 1.0,
+    "core_latency_accuracy": 1.0,
+    "core_latency_p50_ms": 0,
+    "dictation_p50_ms": 208,
+    "core_avg_ms": 78,
+    "held_out_avg_ms": 152,
+    "vs_v3_lite_dict_p50_delta_ms": -152,
+    "latency_sla_ms": 2000,
+    "benchmarked_at": "2026-06-26"
+  }
+}

ir/adapter_config.json

@@ -0,0 +1,22 @@
+{
+  "fine_tune_type": "lora",
+  "role": "compact_ir",
+  "model_hf_repo": "mlx-community/functiongemma-270m-it-4bit",
+  "checkpoint": "adapters.safetensors",
+  "num_layers": 12,
+  "lora_parameters": {
+    "keys": [
+      "self_attn.q_proj",
+      "self_attn.k_proj",
+      "self_attn.v_proj",
+      "self_attn.o_proj",
+      "mlp.gate_proj",
+      "mlp.up_proj",
+      "mlp.down_proj"
+    ],
+    "rank": 8,
+    "scale": 16.0,
+    "dropout": 0.05
+  },
+  "training_pipeline": "gemmaflow-tune FunctionGemma IR v5 push5 compact-intent distill"
+}

ir/adapters.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:231afdddd1fc709d3858ff26dedf7953fb6ec982214fea9a51c5ba5f0755548b
+size 5080337

manifest.json

@@ -0,0 +1,30 @@
+{
+  "product": "v4-lite",
+  "version": "1.0.0",
+  "download_mb": 809,
+  "runner_kind": "compact_ir",
+  "writer_model_config": "configs/model_v5_lfm25_1_2b.yaml",
+  "writer_adapter_path": "artifacts/sft_v5_lfm25_v3lite_writer/adapters",
+  "writer_checkpoint": "promoted_core_100.safetensors",
+  "writer_use_prompt_kv_cache": true,
+  "ir_model_config": "configs/model_v4_functiongemma.yaml",
+  "ir_adapter_path": "artifacts/sft_v5_functiongemma_ir_v5/adapters",
+  "ir_checkpoint": "adapters.safetensors",
+  "ir_prompt_mode": "verbose",
+  "ir_use_prompt_kv_cache": true,
+  "ir_max_tokens": 96,
+  "transcript_first_ir": true,
+  "intent_fast_path": true,
+  "prompt_mode": "verbose",
+  "json_early_stop": true,
+  "heavy_fallback": false,
+  "predecessor": "nsalerni/flowcast-v3-lite",
+  "targets": {
+    "core_accuracy": 0.99,
+    "expanded_accuracy": 0.99,
+    "held_out_accuracy": 0.97,
+    "hot_download_mb_max": 850,
+    "core_latency_p50_ms_max": 350
+  },
+  "notes": "v3-lite stack + promoted writer checkpoint + IR v5 push5; production uses transcript-first + intent fast-path; IR v5 exercised on fallback path (IR model slice)."
+}

writer/adapter_config.json

@@ -0,0 +1,24 @@
+{
+  "fine_tune_type": "lora",
+  "role": "writer",
+  "model_hf_repo": "mlx-community/LFM2.5-1.2B-Instruct-4bit",
+  "checkpoint": "promoted_core_100.safetensors",
+  "num_layers": 16,
+  "lora_parameters": {
+    "keys": [
+      "self_attn.q_proj",
+      "self_attn.k_proj",
+      "self_attn.v_proj",
+      "self_attn.out_proj",
+      "conv.in_proj",
+      "conv.out_proj",
+      "feed_forward.w1",
+      "feed_forward.w2",
+      "feed_forward.w3"
+    ],
+    "rank": 16,
+    "scale": 32.0,
+    "dropout": 0.05
+  },
+  "training_pipeline": "gemmaflow-tune v5 cascade \u2192 core promotion \u2192 dictation KV cache"
+}

writer/adapters.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ceb709ccf7a40ea608c5cc74c247071bbcb0980017f1811f7c55604b4241ab7c
+size 44453426