@@ -12,8 +12,8 @@ The public SDK repository is:
 https://github.com/ofspectrum/python-sdk
 ```
 
-Customer applications should normally install SDK `1.2.1` with
-`pip install "ofspectrum==1.2.1"`; they should not need the private Neo
+Customer applications should normally install SDK `1.3.1` with
+`pip install "ofspectrum==1.3.1"`; they should not need the private Neo
 monorepo source.
 
 If an agent needs SDK source orientation, use the public SDK repository above. From that repository root, inspect these files first:
 
@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.3.1 - 2026-08-24
+
+- `open_stream_pool(..., keepalive_interval_seconds=120)` heartbeats every pooled connection so idle Neo model sessions are not retired.
+- `StreamEncodePool.heartbeat()` sends `{"type": "heartbeat"}` on all slots, silently replaces dead connections, and never raises into the encode path.
+- Opening a stream connection through `admitted` / `ready` is the warmup. Do not send dummy audio just to keep a session hot.
+- Neo-to-model sessions stay warm from real encode/decode work. Heartbeats only refresh idle tracking; they do not bill quota.
+
 ## 1.3.0 - 2026-08-23
 
 - `audio.stream_encode()` reuses a process-local persistent stream pool when `interval` is 0, so repeated TTS-style calls do not open a new WebSocket each time.
 
@@ -1,12 +1,12 @@
 # OfSpectrum Python SDK
 
 Official Python SDK for the OfSpectrum audio watermarking API. This guide
-describes the SDK `1.2.1` contract.
+describes the SDK `1.3.1` contract.
 
 ## Installation
 
 ```bash
-pip install "ofspectrum==1.2.1"
+pip install "ofspectrum==1.3.1"
 ```
 
 Or install from source:
@@ -294,6 +294,7 @@ with client.audio.open_stream_pool(
     strength=1.0,
     smooth=True,
     verify_and_reencode=True,
+    keepalive_interval_seconds=120,
 ) as pool:
     result = pool.encode(tts_wav_bytes, timeout=120.0)
     result.save("watermarked.wav")
@@ -302,12 +303,22 @@ with client.audio.open_stream_pool(
 Pool configuration is fixed when it is opened. `pool.encode()` accepts a file
 path, file object, or bytes and returns the same `EncodeResult` as
 `stream_encode()`. The input channel count must match `channels`; use the
-default mono configuration for EthoVox output. Before sending an operation, the
-SDK probes an existing pooled connection and replaces it if it is stale. Once
+default mono configuration for EthoVox output. Set
+`keepalive_interval_seconds` below Neo's idle window (300 seconds by default)
+so every pooled connection stays warm without dummy audio. Completing
+`admitted` / `ready` is the warmup. Before sending an operation, the SDK
+probes an existing pooled connection and replaces it if it is stale. Once
 operation input starts, the SDK never replays that operation automatically;
 retry at the application level only when the workflow has an idempotency
 boundary.
 
+Real encode and decode traffic keeps Neo-to-model sessions alive. Heartbeats
+only refresh idle tracking and do not consume encode quota. They cannot skip
+hourly connection max-age rotation (`AUDIO_ENCODE_V2_CONNECTION_MAX_AGE_SECONDS`,
+default 3600s) or the 40-minute persistent WebSocket rotation. For a long-lived
+TTS worker, raise max-age (for example 86400) or accept a reconnect about once
+an hour.
+
 ## Notebook Management
 
 Attach notes and media files to tokens. Private notebooks require a credential, and limits depend on your account and token configuration.
 
@@ -29,7 +29,7 @@
     print(f"Remaining: {quota.remaining}/{quota.limit}")
 """
 
-__version__ = "1.3.0"
+__version__ = "1.3.1"
 __author__ = "OfSpectrum"
 
 from .client import AsyncOfSpectrum, OfSpectrum
 
@@ -104,7 +104,7 @@ def _default_headers(self) -> Dict[str, str]:
         """Get default request headers"""
         return {
             "Authorization": f"Bearer {self._api_key}",
-            "User-Agent": "OfSpectrum-Python-SDK/1.3.0",
+            "User-Agent": "OfSpectrum-Python-SDK/1.3.1",
             "Accept": "application/json",
         }
 
@@ -236,7 +236,7 @@ def __init__(
     def _default_headers(self) -> Dict[str, str]:
         return {
             "Authorization": f"Bearer {self._api_key}",
-            "User-Agent": "OfSpectrum-Python-SDK/1.3.0",
+            "User-Agent": "OfSpectrum-Python-SDK/1.3.1",
             "Accept": "application/json",
         }
 
 
@@ -99,6 +99,7 @@ def __init__(
         smooth: bool,
         verify_and_reencode: bool,
         timeout: Optional[float],
+        keepalive_interval_seconds: Optional[float] = None,
     ) -> None:
         self._resource = resource
         self._token_id = token_id
@@ -108,12 +109,22 @@ def __init__(
         self._smooth = smooth
         self._verify_and_reencode = verify_and_reencode
         self._timeout = timeout
+        self._keepalive_interval = keepalive_interval_seconds
         self._slots = [_StreamPoolSlot() for _ in range(connections)]
         self._idle = deque(self._slots)
         self._idle_lock = threading.Lock()
         self._idle_ready = threading.Condition(self._idle_lock)
         self._state_lock = threading.Lock()
         self._closed = False
+        self._keepalive_stop = threading.Event()
+        self._keepalive_thread: Optional[threading.Thread] = None
+        if keepalive_interval_seconds is not None:
+            self._keepalive_thread = threading.Thread(
+                target=self._keepalive_loop,
+                name="ofspectrum-stream-keepalive",
+                daemon=True,
+            )
+            self._keepalive_thread.start()
 
     def __enter__(self) -> "StreamEncodePool":
         return self
@@ -132,6 +143,10 @@ def close(self) -> None:
             if self._closed:
                 return
             self._closed = True
+        self._keepalive_stop.set()
+        thread = self._keepalive_thread
+        if thread is not None and thread is not threading.current_thread():
+            thread.join(timeout=1.0)
         with self._idle_ready:
             self._idle_ready.notify_all()
 
@@ -166,6 +181,77 @@ def close(self) -> None:
             finally:
                 slot.lock.release()
 
+    def heartbeat(self, *, timeout: Optional[float] = None) -> bool:
+        """Refresh every pooled stream connection without encoding audio.
+
+        Busy slots are skipped because an in-flight encode already keeps them
+        alive. Dead connections are replaced silently. This method never raises;
+        a ``False`` result means no slot confirmed an ack, but later ``encode()``
+        still uses the existing fail-open reconnect path.
+        """
+        if self.closed:
+            return False
+        deadline = None
+        if timeout is not None:
+            deadline = time.monotonic() + float(timeout)
+        elif self._timeout is not None:
+            deadline = time.monotonic() + float(self._timeout)
+        confirmed = False
+        for slot in self._slots:
+            if self._heartbeat_slot(slot, deadline):
+                confirmed = True
+        return confirmed
+
+    def _keepalive_loop(self) -> None:
+        interval = self._keepalive_interval
+        if interval is None:
+            return
+        while not self._keepalive_stop.wait(timeout=interval):
+            if self.closed:
+                return
+            self.heartbeat(timeout=self._CONNECT_TIMEOUT_SECONDS)
+
+    def _heartbeat_slot(
+        self,
+        slot: _StreamPoolSlot,
+        deadline: Optional[float],
+    ) -> bool:
+        if not slot.lock.acquire(blocking=False):
+            return True
+        try:
+            if self.closed:
+                return False
+            try:
+                return self._heartbeat_once(slot, deadline)
+            except Exception:
+                self._discard_connection(slot)
+                try:
+                    return self._heartbeat_once(slot, deadline)
+                except Exception:
+                    self._discard_connection(slot)
+                    return False
+        finally:
+            slot.lock.release()
+
+    def _heartbeat_once(
+        self,
+        slot: _StreamPoolSlot,
+        deadline: Optional[float],
+    ) -> bool:
+        self._ensure_connection(slot, deadline)
+        websocket = slot.websocket
+        if websocket is None:
+            return False
+        websocket.send(json.dumps({"type": "heartbeat"}))
+        event = self._control_event(self._recv(websocket, deadline))
+        if event.get("type") != "heartbeat_ack":
+            raise OfSpectrumError(
+                message="Streaming pool received an invalid heartbeat response",
+                code="StreamingPoolProtocol",
+            )
+        slot.last_ok_monotonic = time.monotonic()
+        return True
+
     def encode(
         self,
         audio: Union[str, Path, BinaryIO, bytes],
@@ -754,12 +840,19 @@ def open_stream_pool(
         smooth: bool = True,
         verify_and_reencode: bool = True,
         timeout: Optional[float] = None,
+        keepalive_interval_seconds: Optional[float] = None,
     ) -> StreamEncodePool:
         """Create a thread-safe persistent pool for repeated stream encodes.
 
         Each connection has a stable opaque slot identifier. The pool config is
         fixed at creation time; ``encode()`` accepts file paths, file objects,
         or bytes with the same number of audio channels as the pool.
+
+        ``keepalive_interval_seconds`` sends ``{"type": "heartbeat"}`` on every
+        pooled connection so Neo does not idle-retire the model session. Use a
+        value below the server idle window (default 300s), typically 120. Opening
+        the pool and completing ``admitted`` / ``ready`` warms the connection;
+        do not send dummy audio just to warm up. ``None`` disables keepalive.
         """
         if not token_id:
             raise ValueError("token_id is required")
@@ -783,6 +876,12 @@ def open_stream_pool(
             isinstance(timeout, bool) or not math.isfinite(timeout) or timeout <= 0.0
         ):
             raise ValueError("timeout must be a finite positive number or None")
+        if keepalive_interval_seconds is not None and (
+            isinstance(keepalive_interval_seconds, bool)
+            or not math.isfinite(keepalive_interval_seconds)
+            or keepalive_interval_seconds <= 0.0
+        ):
+            raise ValueError("keepalive_interval_seconds must be a positive number or None")
 
         pool = StreamEncodePool(
             self,
@@ -794,6 +893,7 @@ def open_stream_pool(
             smooth=smooth,
             verify_and_reencode=verify_and_reencode,
             timeout=timeout,
+            keepalive_interval_seconds=keepalive_interval_seconds,
         )
         with self._stream_pools_lock:
             self._stream_pools.add(pool)
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ofspectrum"
-version = "1.3.0"
+version = "1.3.1"
 description = "OfSpectrum Audio Watermarking SDK"
 readme = "README.md"
 license = {text = "MIT"}
 
@@ -1,5 +1,6 @@
 import json
 import threading
+import time
 import uuid
 from collections import deque
 from concurrent.futures import ThreadPoolExecutor
@@ -50,6 +51,8 @@ def send(self, value):
                 with self._condition:
                     self._responses.extend(self._flush_responses.popleft())
                     self._condition.notify_all()
+            elif event_type == "heartbeat":
+                self._queue_response('{"type":"heartbeat_ack"}')
             elif event_type == "close":
                 self._queue_response('{"type":"closed"}')
 
@@ -333,6 +336,92 @@ def test_stream_pool_reconnects_stale_socket_before_sending_next_operation(monke
     assert factory.connections[0].closed is True
 
 
+def test_stream_pool_heartbeat_keeps_every_slot_alive(monkeypatch):
+    factory = _PoolFactory([_success_scenario(), _success_scenario()])
+    monkeypatch.setattr(websockets.sync.client, "connect", factory)
+    client = OfSpectrum(api_key="test-key")
+    pool = client.audio.open_stream_pool("token-1", connections=2)
+    try:
+        assert pool.heartbeat(timeout=2.0) is True
+        assert len(factory.connections) == 2
+        for socket in factory.connections:
+            types = [
+                json.loads(message).get("type")
+                for message in socket.sent
+                if isinstance(message, str)
+            ]
+            assert "heartbeat" in types
+            assert "config" in types
+    finally:
+        client.close()
+
+
+def test_stream_pool_heartbeat_reconnects_dead_socket_without_raising(monkeypatch):
+    factory = _PoolFactory([_success_scenario(), _success_scenario()])
+    original = factory.__call__
+
+    def connect_with_dead_first(_url, **kwargs):
+        socket = original(_url, **kwargs)
+        if len(factory.connections) == 1:
+            inner_send = socket.send
+
+            def send(value):
+                if isinstance(value, str) and json.loads(value).get("type") == "heartbeat":
+                    raise RuntimeError("socket dead")
+                return inner_send(value)
+
+            socket.send = send
+        return socket
+
+    monkeypatch.setattr(websockets.sync.client, "connect", connect_with_dead_first)
+    client = OfSpectrum(api_key="test-key")
+    pool = client.audio.open_stream_pool("token-1", connections=1)
+    try:
+        assert pool.heartbeat(timeout=2.0) is True
+        assert len(factory.connections) == 2
+        assert any(
+            isinstance(message, str) and json.loads(message).get("type") == "heartbeat"
+            for message in factory.connections[1].sent
+        )
+    finally:
+        client.close()
+
+
+def test_stream_pool_keepalive_thread_heartbeats_all_slots(monkeypatch):
+    factory = _PoolFactory([_success_scenario(), _success_scenario()])
+    monkeypatch.setattr(websockets.sync.client, "connect", factory)
+    client = OfSpectrum(api_key="test-key")
+    pool = client.audio.open_stream_pool(
+        "token-1",
+        connections=2,
+        keepalive_interval_seconds=0.05,
+    )
+    try:
+        deadline = time.monotonic() + 2.0
+        while time.monotonic() < deadline:
+            if len(factory.connections) == 2 and all(
+                any(
+                    isinstance(message, str)
+                    and json.loads(message).get("type") == "heartbeat"
+                    for message in socket.sent
+                )
+                for socket in factory.connections
+            ):
+                break
+            time.sleep(0.02)
+        assert len(factory.connections) == 2
+        assert all(
+            any(
+                isinstance(message, str)
+                and json.loads(message).get("type") == "heartbeat"
+                for message in socket.sent
+            )
+            for socket in factory.connections
+        )
+    finally:
+        client.close()
+
+
 def test_stream_pool_does_not_replay_after_operation_input_starts(monkeypatch):
     factory = _PoolFactory(
         [{"responses": [[RuntimeError("connection closed before output")]]}]
 
@@ -12,7 +12,7 @@
 def test_client_version_headers_match_release():
     client = OfSpectrum(api_key="test-key")
     try:
-        assert client._default_headers()["User-Agent"] == "OfSpectrum-Python-SDK/1.3.0"
+        assert client._default_headers()["User-Agent"] == "OfSpectrum-Python-SDK/1.3.1"
     finally:
         client.close()