runtime/prefetch.py

import threading


class PrefetchEngine:
    """Predictively loads upcoming token chunks.

    Uses a lookahead window to submit decode work for chunks the player
    is likely to request next, hiding disk and entropy decode latency.
    """
    def __init__(self, lookahead: int = 4):
        self._lookahead = lookahead
        self._current = 0
        self._running = False
        self._thread: threading.Thread | None = None

    def start(self, current_chunk: int):
        self._current = current_chunk
        self._running = True

    def stop(self):
        self._running = False

    def advance(self, new_current: int):
        self._current = new_current

    def window(self) -> range:
        end = min(self._current + self._lookahead, 1_000_000)
        return range(self._current + 1, end)

    @property
    def lookahead(self) -> int:
        return self._lookahead