Pre-warm the cleanup model when the phone starts recording

The PC unloads its cleanup model after idling to free the GPU, and
reloading takes five to nine seconds. The desktop hides that behind the
hotkey key-down, but the phone gave the PC no signal until the audio
arrived, so the first dictation after a pause paid the whole reload.

The phone API gains POST /v1/warm. It asks Ollama whether the model is
resident rather than trusting the idle timer, and starts the reload in
the background if it is not. The Android app calls it the moment
recording starts and, rate-limited, when a text field gains focus.
Measured: a dictation sent four seconds after warming waited about one
second instead of seven. The default keep-alive rises from 10 to 30
minutes.

LocalFlow 0.2.1; Android 0.1.3 (versionCode 4).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: DatafyingTech

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -88,7 +88,7 @@ body:
     attributes:
       label: LocalFlow version
       description: "`python -m localflow --version`, or the commit you are on."
-      placeholder: "0.2.0"
+      placeholder: "0.2.1"
     validations:
       required: true
 

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to LocalFlow are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.2.1] - 2026-09-12
+
+### Added
+
+- `POST /v1/warm` on the phone API. The PC unloads its cleanup model after idling and reloading
+  it takes several seconds; the desktop hides that behind the hotkey key-down, but a phone gave
+  the PC no such signal, so the first dictation after a pause waited 4 to 9 s. The phone app
+  (0.1.3) now calls this the moment recording starts and when a text field gains focus, so the
+  reload overlaps with speaking. Contract in `docs/API.md`.
+
 ## [0.2.0] - 2026-09-11
 
 ### Added

android/app/build.gradle.kts

@@ -27,8 +27,8 @@ android {
         applicationId = "tech.datafying.localflow"
         minSdk = 26
         targetSdk = 35
-        versionCode = 3
-        versionName = "0.1.2"
+        versionCode = 4
+        versionName = "0.1.3"
     }
 
     signingConfigs {

android/app/src/main/kotlin/tech/datafying/localflow/ApiClient.kt

@@ -52,6 +52,8 @@ class ApiClient(private val settings: Settings) {
         private const val CONNECT_S = 5L
         private const val READ_PTT_S = 30L
         private const val READ_HANDSFREE_S = 120L
+        private const val WARM_CONNECT_S = 2L
+        private const val WARM_READ_S = 3L
         private val WAV = "audio/wav".toMediaType()
 
         const val MSG_URL_BLANK = "No PC address set. Paste the setup line from your PC."
@@ -144,6 +146,32 @@ class ApiClient(private val settings: Settings) {
         )
     }
 
+    /**
+     * POST /v1/warm: ask the PC to start reloading its cleanup model now, so the reload hides
+     * behind the user speaking instead of delaying the first result after an idle spell.
+     * Fire-and-forget: short timeouts, and every failure (including a missing endpoint on an
+     * older PC build) is swallowed. Never throws, never changes any state.
+     */
+    fun warm() {
+        try {
+            val url = baseUrl().newBuilder().addPathSegments("v1/warm").build()
+            val req = Request.Builder()
+                .url(url)
+                .header("Authorization", "Bearer ${settings.token}")
+                .header("User-Agent", userAgent())
+                .post(ByteArray(0).toRequestBody(null))
+                .build()
+            val c = client.newBuilder()
+                .connectTimeout(WARM_CONNECT_S, TimeUnit.SECONDS)
+                .readTimeout(WARM_READ_S, TimeUnit.SECONDS)
+                .writeTimeout(WARM_READ_S, TimeUnit.SECONDS)
+                .build()
+            c.newCall(req).execute().close()
+        } catch (ignored: Exception) {
+            // Best effort only; the dictation call reports real problems.
+        }
+    }
+
     private fun <T> execute(c: OkHttpClient, req: Request, handle: (Int, String) -> T): T {
         try {
             c.newCall(req).execute().use { resp ->

android/app/src/main/kotlin/tech/datafying/localflow/OverlayService.kt

@@ -22,6 +22,7 @@ import android.os.Build
 import android.os.Handler
 import android.os.IBinder
 import android.os.Looper
+import android.os.SystemClock
 import android.os.VibrationEffect
 import android.os.Vibrator
 import android.os.VibratorManager
@@ -62,6 +63,8 @@ class OverlayService : Service(), View.OnTouchListener {
         private const val ERROR_MS = 2500L
         /** Focus hops between fields (and keyboard show/hide) within this window do not blink the dot. */
         private const val HIDE_DEBOUNCE_MS = 350L
+        /** Minimum gap between focus-triggered /v1/warm calls (recording start is not limited). */
+        private const val FOCUS_WARM_INTERVAL_MS = 60_000L
 
         @Volatile
         var isRunning: Boolean = false
@@ -345,8 +348,30 @@ class OverlayService : Service(), View.OnTouchListener {
 
     // ------------------------------------------------------------------ visibility
     private fun onCanType(v: Boolean) {
+        val gainedFocus = v && !canType
         canType = v
         reevaluateVisibility()
+        // A text field just gained focus: the user is likely about to dictate, so nudge the PC
+        // to reload its cleanup model now (rate-limited; harmless when already loaded).
+        if (gainedFocus) warmPc(force = false)
+    }
+
+    // ------------------------------------------------------------------ pre-warm
+    private var lastFocusWarmMs = 0L
+
+    /**
+     * Fire-and-forget POST /v1/warm on the network thread. [force] skips the 60 s rate limit
+     * (used when recording actually starts). Silent when the app is not connected yet.
+     */
+    private fun warmPc(force: Boolean) {
+        if (settings.serverUrl.isBlank() || settings.token.isBlank()) return
+        if (!force) {
+            val now = SystemClock.elapsedRealtime()
+            if (now - lastFocusWarmMs < FOCUS_WARM_INTERVAL_MS) return
+            lastFocusWarmMs = now
+        }
+        if (!::api.isInitialized) return
+        worker.execute { api.warm() }
     }
 
     private fun wantVisible(): Boolean = DotVisibility.decide(
@@ -475,6 +500,7 @@ class OverlayService : Service(), View.OnTouchListener {
             )
             return
         }
+        warmPc(force = true)   // hide the PC's model reload behind the user speaking
         ensureMicType()
         val rec = Recorder(
             maxMillis = HANDSFREE_MAX_MS,

config.example.yaml

@@ -140,7 +140,7 @@ llm:
   segment_words: 400            # a long text is cleaned in sentence-aligned segments of about this
                                 #   many words, then joined. Lower it if the model is short on
                                 #   context; a segment that fails only affects itself.
-  keep_alive: 600               # seconds the model stays in VRAM after a call (-1 = forever)
+  keep_alive: 1800               # seconds the model stays in VRAM after a call (-1 = forever)
   temperature: 0
 
 # ---------------------------------------------------------------- how text is inserted

docs/ANDROID.md

@@ -150,6 +150,12 @@ dot only when a text field is active* in the app; the change applies immediately
 Every state change gives a small haptic tick (switch it off in the app). Sounds are off by
 default.
 
+**First dictation after a pause.** The PC unloads its cleanup model after about 10 idle minutes
+to free the GPU, so the first dictation after a pause can take a few extra seconds while it
+reloads. The app now pre-warms the PC when you tap into a text field and again the moment you
+start recording, so you will rarely notice. If it still happens and the ring turns red, hold to
+talk again while the ring is red and it retries.
+
 Between two hands-free results the phone inserts a single space unless the text already ends in
 a space or a newline. After push-to-talk it never adds trailing whitespace, so you can keep typing.
 

docs/API.md

@@ -16,7 +16,7 @@ Both are built against it. Change it here first.
 | Reached at | `http://<pc-name>.<tailnet>.ts.net` via `tailscale serve`, which proxies port 80 to 8770 |
 | Example | `http://localflow-pc.tail1234.ts.net` (your own tailnet name; `tailscale status` on the PC shows it) |
 | Enabled by | `server.enabled: true` in `config.yaml` (off by default) |
-| Auth | `Authorization: Bearer <server.token>` on every `/v1/*` call except `/v1/health` |
+| Auth | `Authorization: Bearer <server.token>` on `/v1/dictate` and `/v1/warm`; `/v1/health` is open |
 
 The token is generated on first enable, stored in `config.yaml`, and shown in the tray menu under
 **Phone setup**. Use the MagicDNS name, not the raw 100.x IP: `tailscale serve` routes by
@@ -45,6 +45,20 @@ No auth. For the phone's "Test connection" button and for the status page.
 
 `ready` is false while models are still loading; the phone should show "PC is warming up" and retry.
 
+### `POST /v1/warm`
+Auth required, empty body. Call it the moment recording starts. The PC unloads its cleanup model
+after idling (`llm.keep_alive`, 10 minutes by default) and reloading takes several seconds; this
+starts that reload in the background so it overlaps with the user speaking, exactly what the
+desktop hotkey does on key-down. Returns immediately. Cheap and harmless when the model is already
+loaded, so the phone may also call it when a text field gains focus.
+
+```json
+{ "warming": true, "llm_loaded": false, "ready": true }
+```
+
+`llm_loaded` is the state before this call. Errors: 401 bad token; 503 while models are loading
+or the PC is paused.
+
 ### `POST /v1/dictate`
 Auth required. Send audio, get text.
 

localflow/__init__.py

@@ -1,3 +1,3 @@
 """LocalFlow: fully local push-to-talk dictation for Windows 11."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

localflow/__main__.py

@@ -759,7 +759,8 @@ def start_server(self) -> None:
         self._ensure_token()
         try:
             self.server = DictationServer(
-                scfg, pipeline=self.dictate_remote, status=self.server_status, lock=self._pipe_lock,
+                scfg, pipeline=self.dictate_remote, status=self.server_status, warm=self.warm_remote,
+                lock=self._pipe_lock,
                 max_seconds=float(self.cfg["audio"].get("max_seconds", 1200)),
             )
             self.server.start()
@@ -768,6 +769,23 @@ def start_server(self) -> None:
             self.server = None
             self.tray.notify(f"Phone access could not start: {e}", "LocalFlow")
 
+    def warm_remote(self) -> dict:
+        """The phone started recording: reload the cleanup model in the background if it was
+        unloaded after idling, exactly as the desktop does on hotkey key-down."""
+        loaded = True
+        if self.llm is not None and self.llm_ok:
+            try:
+                level = self.cfg["cleanup"].get("handsfree_level", "high")
+                resident = self.llm.is_loaded()  # ask Ollama; the idle timer can be wrong
+                loaded = bool(resident) if resident is not None else not self.llm.needs_warm()
+                if not loaded:
+                    self.llm.warm_now(level=level)
+                else:
+                    self.llm.warm_if_idle(level=level)
+            except Exception as e:  # noqa: BLE001
+                log.debug("warm_remote: %s", e)
+        return {"llm_loaded": loaded}
+
     def stop_server(self) -> None:
         srv, self.server = self.server, None
         if srv is not None: