Add unit tests for MTP module

Add 28 unit tests covering:
- Weight extraction from layer 61
- MTPModule forward pass and initialization
- MTPTransformerBlock
- Weight loading into MTPModule
- Sanitize patching and restoration
- Model ID detection for DeepSeek V3/R1
- Parameter flattening utility
- ModelWithHiddenStates wrapper
- KV cache quantization logic
- Speculative decoding acceptance/rejection logic
- MTPGenerationResponse dataclass
- Integration test with mock model

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.mlx_typings/mlx_lm/generate.pyi

@@ -276,23 +276,24 @@ class BatchGenerator:
         logprobs: mx.array
         finish_reason: Optional[str]
 
-    unprocessed_prompts: List[Any]
-
     def __init__(
         self,
-        model: nn.Module,
+        model,
         max_tokens: int = ...,
-        stop_tokens: Optional[set[int]] = ...,
+        stop_tokens: Optional[set] = ...,
         sampler: Optional[Callable[[mx.array], mx.array]] = ...,
         completion_batch_size: int = ...,
         prefill_batch_size: int = ...,
         prefill_step_size: int = ...,
     ) -> None: ...
     def insert(
-        self, prompts: List[List[int]], max_tokens: Union[List[int], int, None] = ...
-    ) -> List[int]: ...
-    def stats(self) -> BatchStats: ...
-    def next(self) -> List[Response]: ...
+        self, prompts, max_tokens: Union[List[int], int, None] = ...
+    ):  # -> list[Any]:
+        ...
+    def stats(self):  # -> BatchStats:
+        ...
+    def next(self):  # -> list[Any]:
+        ...
 
 def batch_generate(
     model,

.mlx_typings/mlx_lm/tokenizer_utils.pyi

@@ -39,18 +39,12 @@ class StreamingDetokenizer:
     """
 
     __slots__ = ...
-    tokens: list[int]
-    def reset(self) -> None: ...
-    def add_token(self, token: int) -> None: ...
-    def finalize(self) -> None: ...
+    def reset(self): ...
+    def add_token(self, token): ...
+    def finalize(self): ...
     @property
-    def text(self) -> str:
-        """The full text decoded so far."""
-        ...
-    @property
-    def last_segment(self) -> str:
+    def last_segment(self):
         """Return the last segment of readable text since last time this property was accessed."""
-        ...
 
 class NaiveStreamingDetokenizer(StreamingDetokenizer):
     """NaiveStreamingDetokenizer relies on the underlying tokenizer
@@ -114,7 +108,6 @@ class TokenizerWrapper:
     _tokenizer: PreTrainedTokenizerFast
     eos_token_id: int | None
     eos_token: str | None
-    eos_token_ids: list[int] | None
     bos_token_id: int | None
     bos_token: str | None
     vocab_size: int

AGENTS.md

@@ -116,45 +116,6 @@ From .cursorrules:
 - Catch exceptions only where you can handle them meaningfully
 - Use `@final` and immutability wherever applicable
 
-## Model Storage
-
-Downloaded models are stored in `~/.exo/models/` (not the standard HuggingFace cache location).
-
-## Creating Model Instances via API
-
-When testing with the API, you must first create a model instance before sending chat completions:
-
-```bash
-# 1. Get instance previews for a model
-curl "http://localhost:52415/instance/previews?model_id=llama-3.2-1b"
-
-# 2. Create an instance from the first valid preview
-INSTANCE=$(curl -s "http://localhost:52415/instance/previews?model_id=llama-3.2-1b" | jq -c '.previews[] | select(.error == null) | .instance' | head -n1)
-curl -X POST http://localhost:52415/instance -H 'Content-Type: application/json' -d "{\"instance\": $INSTANCE}"
-
-# 3. Wait for the runner to become ready (check logs for "runner ready")
-
-# 4. Send chat completions using the full model ID
-curl -X POST http://localhost:52415/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"model": "mlx-community/Llama-3.2-1B-Instruct-4bit", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 50}'
-```
-
-## Logs
-
-Exo logs are stored in `~/.exo/exo.log`. This is useful for debugging runner crashes and distributed issues.
-
 ## Testing
 
 Tests use pytest-asyncio with `asyncio_mode = "auto"`. Tests are in `tests/` subdirectories alongside the code they test. The `EXO_TESTS=1` env var is set during tests.
-
-### Distributed Testing
-
-When running distributed tests across multiple machines, use `EXO_LIBP2P_NAMESPACE` to isolate your test cluster from other exo instances on the same network:
-
-```bash
-# On each machine in the test cluster, use the same unique namespace
-EXO_LIBP2P_NAMESPACE=my-test-cluster uv run exo
-```
-
-This prevents your test cluster from discovering and interfering with production or other developers' exo clusters.

src/exo/shared/types/worker/runners.py

@@ -50,9 +50,7 @@ class RunnerReady(BaseRunnerStatus):
 
 
 class RunnerRunning(BaseRunnerStatus):
-    """Runner is processing requests and can accept more (continuous batching)."""
-
-    active_requests: int = 0
+    pass
 
 
 class RunnerShuttingDown(BaseRunnerStatus):

src/exo/worker/engines/mlx/constants.py

@@ -13,3 +13,8 @@ KV_CACHE_BITS: int | None = None
 
 # TODO: We should really make this opt-in, but Kimi requires trust_remote_code=True
 TRUST_REMOTE_CODE: bool = True
+
+# Multi-Token Prediction (MTP) configuration for DeepSeek V3
+# MTP enables speculative decoding using the model's built-in draft layer
+MTP_ENABLED: bool = True  # Feature flag to enable/disable MTP
+MTP_NUM_DRAFT_TOKENS: int = 1  # Number of tokens to draft (vLLM reports k=1 is optimal)

src/exo/worker/engines/mlx/generator/batch_engine.py

@@ -1,302 +0,0 @@
-"""Batch generation engine using mlx_lm's BatchGenerator for continuous batching."""
-
-import time
-from dataclasses import dataclass, field
-
-import mlx.core as mx
-from mlx_lm.generate import BatchGenerator
-from mlx_lm.sample_utils import make_sampler
-from mlx_lm.tokenizer_utils import StreamingDetokenizer, TokenizerWrapper
-
-from exo.shared.types.api import FinishReason, GenerationStats
-from exo.shared.types.common import CommandId
-from exo.shared.types.memory import Memory
-from exo.shared.types.tasks import ChatCompletionTaskParams, TaskId
-from exo.shared.types.worker.runner_response import GenerationResponse
-from exo.worker.engines.mlx import Model
-from exo.worker.engines.mlx.constants import MAX_TOKENS
-from exo.worker.engines.mlx.generator.distributed_sync import share_object
-from exo.worker.engines.mlx.utils_mlx import apply_chat_template
-from exo.worker.runner.bootstrap import logger
-
-
-@dataclass
-class ActiveRequest:
-    """Tracks an active request in the batch."""
-
-    command_id: CommandId
-    task_id: TaskId
-    uid: int  # BatchGenerator's internal ID
-    detokenizer: StreamingDetokenizer
-    tokens_generated: int = 0
-    prompt_tokens: int = 0
-    start_time: float = field(default_factory=time.perf_counter)
-
-
-@dataclass
-class BatchedGenerationResponse:
-    """Response from batch engine, tagged with command_id and task_id."""
-
-    command_id: CommandId
-    task_id: TaskId
-    response: GenerationResponse
-
-
-class BatchGenerationEngine:
-    """Manages continuous batching using mlx_lm's BatchGenerator."""
-
-    def __init__(
-        self,
-        model: Model,
-        tokenizer: TokenizerWrapper,
-        group: mx.distributed.Group | None = None,
-        max_tokens: int = MAX_TOKENS,
-        completion_batch_size: int = 32,
-        prefill_batch_size: int = 8,
-        prefill_step_size: int = 2048,
-    ):
-        self.model = model
-        self.tokenizer = tokenizer
-        self.max_tokens = max_tokens
-        self.active_requests: dict[int, ActiveRequest] = {}
-        self._pending_inserts: list[
-            tuple[CommandId, TaskId, ChatCompletionTaskParams]
-        ] = []
-        self._pending_completions: list[
-            int
-        ] = []  # UIDs completed but not yet synced/removed
-
-        self.group = group
-        self.rank = group.rank() if group else 0
-        self.is_distributed = group is not None and group.size() > 1
-
-        sampler = make_sampler(temp=0.7, top_p=1.0)
-
-        eos_tokens: set[int] = set(tokenizer.eos_token_ids or [])
-
-        self.batch_gen: BatchGenerator = BatchGenerator(
-            model=model,
-            max_tokens=max_tokens,
-            stop_tokens=eos_tokens,
-            sampler=sampler,
-            completion_batch_size=completion_batch_size,
-            prefill_batch_size=prefill_batch_size,
-            prefill_step_size=prefill_step_size,
-        )
-
-        logger.info(
-            f"BatchGenerationEngine initialized with completion_batch_size={completion_batch_size}, "
-            f"prefill_batch_size={prefill_batch_size}, distributed={self.is_distributed}"
-        )
-
-    def queue_request(
-        self,
-        command_id: CommandId,
-        task_id: TaskId,
-        task_params: ChatCompletionTaskParams,
-    ) -> None:
-        """Queue a request for insertion. Only rank 0 should call this.
-
-        In distributed mode, rank 0 receives tasks from the control plane and
-        queues them here. The actual insertion happens in sync_and_insert_pending()
-        which ensures all ranks insert the same requests together.
-        """
-        assert self.rank == 0, "Only rank 0 should queue requests"
-        self._pending_inserts.append((command_id, task_id, task_params))
-        logger.info(
-            f"Queued request {command_id} for insertion (pending={len(self._pending_inserts)})"
-        )
-
-    def sync_and_insert_pending(self) -> list[int]:
-        """Sync pending inserts across ranks and insert them. Returns UIDs.
-
-        This method ensures all ranks insert the same requests in the same order.
-        In non-distributed mode, it simply inserts all pending requests.
-        In distributed mode, it broadcasts pending requests from rank 0 to all ranks.
-
-        Batches all pending inserts into a single batch_gen.insert() call for
-        efficient prefill batching.
-        """
-        inserts_to_process: list[tuple[CommandId, TaskId, ChatCompletionTaskParams]]
-
-        if not self.is_distributed:
-            # Non-distributed: just insert directly from pending
-            inserts_to_process = list(self._pending_inserts)
-        else:
-            # Distributed: broadcast pending inserts from rank 0 to all ranks
-            assert self.group is not None
-            pending_data = self._pending_inserts if self.rank == 0 else None
-            synced_data = share_object(pending_data, self.rank, self.group)
-
-            if synced_data is None:
-                self._pending_inserts.clear()
-                return []
-
-            inserts_to_process = synced_data
-
-        if not inserts_to_process:
-            self._pending_inserts.clear()
-            return []
-
-        # Prepare all requests for batched insertion
-        all_tokens: list[list[int]] = []
-        all_max_tokens: list[int] = []
-        all_prompt_tokens: list[int] = []
-        request_info: list[tuple[CommandId, TaskId]] = []
-
-        for cmd_id, task_id, params in inserts_to_process:
-            prompt_str = apply_chat_template(self.tokenizer, params)
-            tokens: list[int] = self.tokenizer.encode(
-                prompt_str, add_special_tokens=False
-            )
-            max_tokens = params.max_tokens or self.max_tokens
-
-            all_tokens.append(tokens)
-            all_max_tokens.append(max_tokens)
-            all_prompt_tokens.append(len(tokens))
-            request_info.append((cmd_id, task_id))
-
-        # Single batched insert for efficient prefill
-        uids = self.batch_gen.insert(all_tokens, max_tokens=all_max_tokens)
-
-        # Track all inserted requests
-        for i, uid in enumerate(uids):
-            cmd_id, task_id = request_info[i]
-            self.active_requests[uid] = ActiveRequest(
-                command_id=cmd_id,
-                task_id=task_id,
-                uid=uid,
-                detokenizer=self.tokenizer.detokenizer,
-                prompt_tokens=all_prompt_tokens[i],
-            )
-            logger.info(
-                f"Inserted request {cmd_id} with uid={uid}, prompt_tokens={all_prompt_tokens[i]}, max_tokens={all_max_tokens[i]}"
-            )
-
-        self._pending_inserts.clear()
-        return uids
-
-    def step(self) -> list[BatchedGenerationResponse]:
-        """Run one decode step. Tracks completions but does not sync - call sync_completions() at budget boundaries."""
-        responses = self.batch_gen.next()
-        if not responses:
-            return []
-
-        results: list[BatchedGenerationResponse] = []
-
-        for r in responses:
-            uid: int = r.uid
-            req = self.active_requests.get(uid)
-            if req is None:
-                logger.warning(f"Received response for unknown uid={uid}")
-                continue
-
-            req.tokens_generated += 1
-
-            # Decode the token
-            token: int = r.token
-            req.detokenizer.add_token(token)
-            text: str = req.detokenizer.last_segment
-
-            stats: GenerationStats | None = None
-            finish_reason: FinishReason | None = None
-
-            raw_finish_reason: str | None = r.finish_reason
-            if raw_finish_reason is not None:
-                # Finalize to get remaining text
-                req.detokenizer.finalize()
-                text = req.detokenizer.last_segment
-
-                elapsed = time.perf_counter() - req.start_time
-                generation_tps = req.tokens_generated / elapsed if elapsed > 0 else 0.0
-
-                stats = GenerationStats(
-                    prompt_tps=0.0,  # Not tracked per-request in batch mode
-                    generation_tps=generation_tps,
-                    prompt_tokens=req.prompt_tokens,
-                    generation_tokens=req.tokens_generated,
-                    peak_memory_usage=Memory.from_gb(mx.get_peak_memory() / 1e9),
-                )
-
-                if raw_finish_reason == "stop":
-                    finish_reason = "stop"
-                elif raw_finish_reason == "length":
-                    finish_reason = "length"
-                else:
-                    logger.warning(f"Unknown finish_reason: {raw_finish_reason}")
-                    finish_reason = "stop"
-
-                # Track completion but don't remove yet - wait for sync_completions()
-                self._pending_completions.append(uid)
-                logger.info(
-                    f"Request {req.command_id} completed: {req.tokens_generated} tokens, {generation_tps:.2f} tps, reason={finish_reason}"
-                )
-
-            results.append(
-                BatchedGenerationResponse(
-                    command_id=req.command_id,
-                    task_id=req.task_id,
-                    response=GenerationResponse(
-                        text=text, token=token, finish_reason=finish_reason, stats=stats
-                    ),
-                )
-            )
-
-        # In non-distributed mode, clean up completions immediately
-        if not self.is_distributed:
-            self._remove_completed()
-
-        return results
-
-    def sync_completions(self) -> None:
-        """Sync and remove completed requests. Call at time budget boundaries in distributed mode."""
-        if not self.is_distributed:
-            # Non-distributed: early return if nothing to do
-            if not self._pending_completions:
-                return
-            self._remove_completed()
-            return
-
-        # Distributed mode: ALWAYS sync to ensure all ranks participate in collective op
-        # This prevents deadlock if one rank has completions and another doesn't
-        assert self.group is not None
-        synced_uids = share_object(
-            self._pending_completions if self.rank == 0 else None,
-            self.rank,
-            self.group,
-        )
-        if synced_uids:
-            self._pending_completions = synced_uids
-
-        self._remove_completed()
-
-    def _remove_completed(self) -> None:
-        """Remove completed requests from tracking."""
-        for uid in self._pending_completions:
-            if uid in self.active_requests:
-                del self.active_requests[uid]
-        self._pending_completions.clear()
-
-    @property
-    def has_active_requests(self) -> bool:
-        return bool(self.active_requests or self.batch_gen.unprocessed_prompts)
-
-    @property
-    def has_pending_inserts(self) -> bool:
-        return bool(self._pending_inserts)
-
-    @property
-    def active_count(self) -> int:
-        return len(self.active_requests)
-
-    @property
-    def pending_count(self) -> int:
-        return len(self.batch_gen.unprocessed_prompts)
-
-    @property
-    def pending_insert_count(self) -> int:
-        return len(self._pending_inserts)
-
-    @property
-    def has_pending_completions(self) -> bool:
-        return bool(self._pending_completions)

src/exo/worker/engines/mlx/generator/distributed_sync.py

@@ -1,30 +0,0 @@
-"""Distributed sync utilities using mx.distributed.all_sum() to broadcast from rank 0."""
-
-# pyright: reportAny=false
-
-import pickle
-from typing import TypeVar, cast
-
-import mlx.core as mx
-
-T = TypeVar("T")
-
-
-def share_object(obj: T | None, rank: int, group: mx.distributed.Group) -> T | None:
-    """Broadcast object from rank 0 to all ranks. Two-phase: size then data."""
-    if rank == 0:
-        if obj is None:
-            mx.eval(mx.distributed.all_sum(mx.array([0]), group=group))
-            return None
-        data = mx.array(list(pickle.dumps(obj)), dtype=mx.uint8)
-        mx.eval(mx.distributed.all_sum(mx.array([data.size]), group=group))
-        mx.eval(mx.distributed.all_sum(data, group=group))
-        return obj
-    else:
-        size = int(mx.distributed.all_sum(mx.array([0]), group=group).item())
-        if size == 0:
-            return None
-        data = mx.zeros(size, dtype=mx.uint8)
-        data = mx.distributed.all_sum(data, group=group)
-        mx.eval(data)
-        return cast(T, pickle.loads(bytes(cast(list[int], data.tolist()))))

src/exo/worker/engines/mlx/generator/generate.py

@@ -19,7 +19,13 @@ from exo.shared.types.worker.runner_response import (
     GenerationResponse,
 )
 from exo.worker.engines.mlx import Model
-from exo.worker.engines.mlx.constants import KV_BITS, KV_GROUP_SIZE, MAX_TOKENS
+from exo.worker.engines.mlx.constants import (
+    KV_BITS,
+    KV_GROUP_SIZE,
+    MAX_TOKENS,
+    MTP_ENABLED,
+    MTP_NUM_DRAFT_TOKENS,
+)
 from exo.worker.engines.mlx.utils_mlx import (
     apply_chat_template,
     make_kv_cache,
@@ -115,6 +121,11 @@ def eos_ids_from_tokenizer(tokenizer: TokenizerWrapper) -> list[int]:
     return eos
 
 
+def _has_mtp_module(model: Model) -> bool:
+    """Check if the model has an attached MTP module."""
+    return hasattr(model, "mtp_module") and model.mtp_module is not None  # type: ignore[attr-defined]
+
+
 def mlx_generate(
     model: Model,
     tokenizer: TokenizerWrapper,
@@ -145,6 +156,43 @@ def mlx_generate(
     )
 
     max_tokens = task.max_tokens or MAX_TOKENS
+
+    # Check if we should use MTP speculative decoding
+    use_mtp = MTP_ENABLED and _has_mtp_module(model)
+
+    if use_mtp:
+        logger.info("Using MTP speculative decoding")
+        yield from _mlx_generate_with_mtp(
+            model=model,
+            tokenizer=tokenizer,
+            prompt=prompt,
+            max_tokens=max_tokens,
+            sampler=sampler,
+            logits_processors=logits_processors,
+            prompt_cache=caches,
+        )
+    else:
+        yield from _mlx_generate_standard(
+            model=model,
+            tokenizer=tokenizer,
+            prompt=prompt,
+            max_tokens=max_tokens,
+            sampler=sampler,
+            logits_processors=logits_processors,
+            prompt_cache=caches,
+        )
+
+
+def _mlx_generate_standard(
+    model: Model,
+    tokenizer: TokenizerWrapper,
+    prompt: str,
+    max_tokens: int,
+    sampler: Callable[[mx.array], mx.array],
+    logits_processors: list[Callable[[mx.array, mx.array], mx.array]],
+    prompt_cache: list[KVCache | Any],
+) -> Generator[GenerationResponse]:
+    """Standard generation path using mlx_lm stream_generate."""
     for out in stream_generate(
         model=model,
         tokenizer=tokenizer,
@@ -152,7 +200,7 @@ def mlx_generate(
         max_tokens=max_tokens,
         sampler=sampler,
         logits_processors=logits_processors,
-        prompt_cache=caches,
+        prompt_cache=prompt_cache,
         # TODO: Dynamically change prefill step size to be the maximum possible without timing out.
         prefill_step_size=2048,
         kv_group_size=KV_GROUP_SIZE,
@@ -187,4 +235,64 @@ def mlx_generate(
         if out.finish_reason is not None:
             break
 
+
+def _mlx_generate_with_mtp(
+    model: Model,
+    tokenizer: TokenizerWrapper,
+    prompt: str,
+    max_tokens: int,
+    sampler: Callable[[mx.array], mx.array],
+    logits_processors: list[Callable[[mx.array, mx.array], mx.array]],
+    prompt_cache: list[KVCache | Any],
+) -> Generator[GenerationResponse]:
+    """MTP speculative decoding generation path.
+
+    Uses the model's attached MTP module for speculative decoding,
+    which can provide 1.5-2x speedup with ~81% acceptance rate.
+    """
+    from exo.worker.engines.mlx.mtp.speculative_decode import mtp_speculative_generate
+
+    mtp_module = model.mtp_module  # type: ignore[attr-defined]
+
+    for out in mtp_speculative_generate(
+        model=model,
+        mtp_module=mtp_module,
+        tokenizer=tokenizer,
+        prompt=prompt,
+        max_tokens=max_tokens,
+        sampler=sampler,
+        logits_processors=logits_processors,
+        prompt_cache=prompt_cache,
+        num_draft_tokens=MTP_NUM_DRAFT_TOKENS,
+        prefill_step_size=2048,
+        kv_group_size=KV_GROUP_SIZE if KV_GROUP_SIZE is not None else 64,
+        kv_bits=KV_BITS,
+    ):
+        logger.info(f"{out.text} (from_draft={out.from_draft})")
+
+        stats: GenerationStats | None = None
+        if out.finish_reason is not None:
+            stats = GenerationStats(
+                prompt_tps=float(out.prompt_tps),
+                generation_tps=float(out.generation_tps),
+                prompt_tokens=int(out.prompt_tokens),
+                generation_tokens=int(out.generation_tokens),
+                peak_memory_usage=Memory.from_gb(out.peak_memory),
+            )
+
+            if out.finish_reason not in get_args(FinishReason):
+                logger.warning(
+                    f"Model generated unexpected finish_reason: {out.finish_reason}"
+                )
+
+        yield GenerationResponse(
+            text=out.text,
+            token=out.token,
+            finish_reason=cast(FinishReason | None, out.finish_reason),
+            stats=stats,
+        )
+
+        if out.finish_reason is not None:
+            break
+
         # TODO: Do we want an mx_barrier?

src/exo/worker/engines/mlx/generator/time_budget.py

@@ -1,104 +0,0 @@
-"""Time budget iterator for controlling generation loop timing in distributed mode.
-
-Based on mlx-lm's TimeBudget pattern - runs for a time budget then syncs,
-rather than syncing every token. This reduces distributed sync overhead.
-"""
-
-import time
-from typing import Iterator
-
-import mlx.core as mx
-
-from exo.worker.runner.bootstrap import logger
-
-generation_stream = mx.new_stream(mx.default_device())
-
-
-class TimeBudget(Iterator[None]):
-    """Controls generation loop timing, syncing across ranks periodically.
-
-    In distributed mode, periodically syncs timing across all ranks to
-    dynamically adjust iteration count based on actual performance.
-
-    In non-distributed mode, simply runs for the time budget.
-
-    Usage:
-        for _ in TimeBudget(budget=0.5):
-            batch_engine.step()
-            # ... process responses ...
-    """
-
-    def __init__(
-        self,
-        budget: float = 0.5,
-        iterations: int = 25,
-        sync_frequency: int = 10,
-        group: mx.distributed.Group | None = None,
-    ):
-        """Initialize TimeBudget.
-
-        Args:
-            budget: Time budget in seconds before yielding control
-            iterations: Initial number of iterations per budget period (distributed only)
-            sync_frequency: How often to sync timing across ranks (distributed only)
-            group: Distributed group, or None for non-distributed mode
-        """
-        self._budget = budget
-        self._iterations = iterations
-        self._sync_frequency = sync_frequency
-        self._group = group
-        self._is_distributed = group is not None and group.size() > 1
-
-        # Runtime state
-        self._start: float = 0.0
-        self._current_iterations: int = 0
-        self._loops: int = 0
-        self._time_spent: float = 0.0
-
-    def __iter__(self) -> "TimeBudget":
-        self._start = time.perf_counter()
-        self._current_iterations = 0
-        return self
-
-    def __next__(self) -> None:
-        if not self._is_distributed:
-            # Non-distributed: just check time budget
-            if time.perf_counter() - self._start > self._budget:
-                raise StopIteration()
-            return None
-
-        # Distributed mode: iteration-based with periodic timing sync
-        self._current_iterations += 1
-        if self._current_iterations > self._iterations:
-            self._loops += 1
-            self._time_spent += time.perf_counter() - self._start
-
-            if self._loops % self._sync_frequency == 0:
-                # Sync timing across all ranks
-                assert self._group is not None
-                with mx.stream(generation_stream):
-                    time_array = mx.array([self._time_spent], dtype=mx.float32)
-                    total_time = mx.distributed.all_sum(time_array, group=self._group)
-                    mx.eval(total_time)
-                    loop_time = float(total_time.item())
-
-                avg_loop_time = loop_time / (self._group.size() * self._sync_frequency)
-
-                if avg_loop_time > 0:
-                    factor = self._budget / avg_loop_time
-                    self._iterations = max(round(self._iterations * factor), 1)
-                    logger.debug(
-                        f"TimeBudget adjusted iterations to {self._iterations}"
-                    )
-
-                self._loops = 0
-                self._time_spent = 0.0
-
-            raise StopIteration()
-
-        return None
-
-    @property
-    def iterations(self) -> int:
-        """Current iterations per budget period."""
-        return self._iterations

src/exo/worker/engines/mlx/mtp/__init__.py

@@ -0,0 +1,6 @@
+"""Multi-Token Prediction (MTP) module for DeepSeek V3 speculative decoding."""
+
+from exo.worker.engines.mlx.mtp.module import MTPModule
+from exo.worker.engines.mlx.mtp.speculative_decode import mtp_speculative_generate
+
+__all__ = ["MTPModule", "mtp_speculative_generate"]

src/exo/worker/engines/mlx/mtp/module.py

@@ -0,0 +1,207 @@
+"""MTP Module for DeepSeek V3 Multi-Token Prediction.
+
+The MTP architecture predicts one additional token ahead using:
+1. hnorm - RMSNorm for hidden state normalization
+2. enorm - RMSNorm for embedding normalization
+3. eh_proj - Linear(2*hidden_size -> hidden_size) projection
+4. transformer_block - Single decoder layer (attention + MLP)
+5. Shared embedding/lm_head from main model
+
+Forward pass:
+    h_norm = hnorm(hidden_state)
+    e_norm = enorm(embed(token))
+    projected = eh_proj(concat([h_norm, e_norm]))
+    new_hidden = transformer_block(projected)
+    logits = lm_head(output_norm(new_hidden))
+"""
+
+from typing import Any
+
+import mlx.core as mx
+import mlx.nn as nn
+from mlx_lm.models.cache import KVCache
+from mlx_lm.models.deepseek_v3 import (
+    DeepseekV3Attention,
+    DeepseekV3MLP,
+    ModelArgs,
+)
+
+MTP_LAYER_INDEX = 61
+
+
+class MTPModule(nn.Module):
+    """Multi-Token Prediction module for DeepSeek V3.
+
+    This module is initialized from the layer 61 weights that are normally
+    discarded during model loading. It enables speculative decoding by
+    predicting one token ahead using the hidden state from the main model.
+    """
+
+    def __init__(
+        self,
+        config: ModelArgs,
+        shared_embedding: nn.Embedding,
+        shared_lm_head: nn.Linear,
+        output_norm: nn.RMSNorm,
+    ) -> None:
+        super().__init__()
+        self.config = config
+
+        # MTP-specific normalization layers
+        self.hnorm = nn.RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+        self.enorm = nn.RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+
+        # Projection: concatenated [hidden, embedding] -> hidden_size
+        self.eh_proj = nn.Linear(2 * config.hidden_size, config.hidden_size, bias=False)
+
+        # Single transformer block for MTP
+        # Use a dense MLP since this is just a single layer
+        self.transformer_block = MTPTransformerBlock(config)
+
+        # Share embedding and lm_head with main model
+        self._shared_embedding = shared_embedding
+        self._shared_lm_head = shared_lm_head
+        self._output_norm = output_norm
+
+    def __call__(
+        self,
+        hidden_state: mx.array,
+        draft_token: mx.array,
+        cache: KVCache | None = None,
+        mask: mx.array | None = None,
+    ) -> tuple[mx.array, mx.array]:
+        """Forward pass for MTP.
+
+        Args:
+            hidden_state: Hidden state from main model [batch, seq_len, hidden_size]
+            draft_token: Token to embed and combine with hidden state [batch, seq_len]
+            cache: Optional KV cache for the MTP transformer block
+            mask: Optional attention mask
+
+        Returns:
+            tuple of (logits, new_hidden_state)
+        """
+        # Get embedding of draft token
+        embedding = self._shared_embedding(draft_token)
+
+        # Normalize hidden state and embedding
+        h_norm = self.hnorm(hidden_state)
+        e_norm = self.enorm(embedding)
+
+        # Project concatenated representation
+        concatenated = mx.concatenate([h_norm, e_norm], axis=-1)
+        projected = self.eh_proj(concatenated)
+
+        # Pass through single transformer block
+        new_hidden = self.transformer_block(projected, mask=mask, cache=cache)
+
+        # Apply output norm and get logits
+        normed_hidden = self._output_norm(new_hidden)
+        logits = self._shared_lm_head(normed_hidden)
+
+        return logits, new_hidden
+
+
+class MTPTransformerBlock(nn.Module):
+    """Single transformer block for MTP.
+
+    This is similar to DeepseekV3DecoderLayer but uses a dense MLP
+    instead of MoE since this is just for the single MTP layer.
+    """
+
+    def __init__(self, config: ModelArgs) -> None:
+        super().__init__()
+        self.self_attn = DeepseekV3Attention(config)
+        # MTP uses dense MLP, not MoE
+        self.mlp = DeepseekV3MLP(config)
+        self.input_layernorm = nn.RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+        self.post_attention_layernorm = nn.RMSNorm(
+            config.hidden_size, eps=config.rms_norm_eps
+        )
+
+    def __call__(
+        self,
+        x: mx.array,
+        mask: mx.array | None = None,
+        cache: Any | None = None,
+    ) -> mx.array:
+        """Forward pass with residual connections."""
+        r = self.self_attn(self.input_layernorm(x), mask, cache)
+        h = x + r
+        r = self.mlp(self.post_attention_layernorm(h))
+        return h + r
+
+
+def extract_mtp_weights(weights: dict[str, mx.array]) -> dict[str, mx.array]:
+    """Extract MTP-specific weights from layer 61.
+
+    The MTP layer has these weight patterns:
+    - model.layers.61.enorm.weight -> MTP embedding normalization
+    - model.layers.61.hnorm.weight -> MTP hidden normalization
+    - model.layers.61.eh_proj.weight -> MTP projection layer
+    - model.layers.61.self_attn.* -> MTP attention
+    - model.layers.61.input_layernorm.* -> MTP layer norms
+    - model.layers.61.post_attention_layernorm.*
+    - model.layers.61.mlp.* -> MTP MLP (dense, not MoE)
+
+    Args:
+        weights: Full model weights dict
+
+    Returns:
+        Dict of MTP-specific weights with keys renamed for MTPModule
+    """
+    mtp_weights: dict[str, mx.array] = {}
+    mtp_prefix = f"model.layers.{MTP_LAYER_INDEX}."
+
+    for key, value in weights.items():
+        if key.startswith(mtp_prefix):
+            # Remove the layer prefix to get relative path
+            new_key = key[len(mtp_prefix) :]
+            mtp_weights[new_key] = value
+
+    return mtp_weights
+
+
+def load_mtp_weights_into_module(
+    mtp_module: MTPModule,
+    mtp_weights: dict[str, mx.array],
+) -> None:
+    """Load extracted MTP weights into the MTPModule.
+
+    Args:
+        mtp_module: The MTPModule instance to load weights into
+        mtp_weights: Extracted MTP weights from extract_mtp_weights()
+    """
+    # Map weight names to module attributes
+    weight_mapping: dict[str, str] = {
+        "enorm.weight": "enorm.weight",
+        "hnorm.weight": "hnorm.weight",
+        "eh_proj.weight": "eh_proj.weight",
+    }
+
+    # Load direct mappings
+    for src_name, dst_name in weight_mapping.items():
+        if src_name in mtp_weights:
+            parts = dst_name.split(".")
+            obj: Any = mtp_module
+            for part in parts[:-1]:
+                obj = getattr(obj, part)
+            setattr(obj, parts[-1], mtp_weights[src_name])
+
+    # Load transformer block weights (self_attn, mlp, layer norms)
+    transformer_prefixes = [
+        "self_attn",
+        "mlp",
+        "input_layernorm",
+        "post_attention_layernorm",
+    ]
+
+    for prefix in transformer_prefixes:
+        for key, value in mtp_weights.items():
+            if key.startswith(prefix):
+                # Navigate to the correct attribute
+                parts = key.split(".")
+                obj = mtp_module.transformer_block
+                for part in parts[:-1]:
+                    obj = getattr(obj, part)
+                setattr(obj, parts[-1], value)

src/exo/worker/engines/mlx/mtp/speculative_decode.py

@@ -0,0 +1,506 @@
+"""MTP Speculative Decoding for DeepSeek V3.
+
+This module implements speculative decoding using the Multi-Token Prediction (MTP)
+layer from DeepSeek V3. The key difference from standard speculative decoding is
+that MTP requires hidden states from the main model, not just token predictions.
+
+Based on vLLM/SGLang research:
+- 81-82% acceptance rate with k=1
+- 1.5-2x speedup at low QPS
+"""
+
+import functools
+import time
+from collections.abc import Callable, Generator
+from dataclasses import dataclass
+from typing import Any, cast
+
+import mlx.core as mx
+import mlx.nn as nn
+from mlx_lm.models import cache
+from mlx_lm.models.cache import KVCache
+from mlx_lm.tokenizer_utils import TokenizerWrapper
+
+from exo.worker.engines.mlx.mtp.module import MTPModule
+
+# Generation stream for async operations
+generation_stream = mx.new_stream(mx.default_device())
+
+
+@dataclass
+class MTPGenerationResponse:
+    """Response from MTP speculative generation.
+
+    Attributes:
+        text: The next segment of decoded text.
+        token: The next token.
+        logprobs: A vector of log probabilities.
+        from_draft: Whether the token was generated by the MTP draft module.
+        prompt_tokens: The number of tokens in the prompt.
+        prompt_tps: The prompt processing tokens-per-second.
+        generation_tokens: The number of generated tokens.
+        generation_tps: The tokens-per-second for generation.
+        peak_memory: The peak memory used so far in GB.
+        finish_reason: The reason the response is being sent: "length", "stop" or None.
+    """
+
+    text: str
+    token: int
+    logprobs: mx.array
+    from_draft: bool
+    prompt_tokens: int
+    prompt_tps: float
+    generation_tokens: int
+    generation_tps: float
+    peak_memory: float
+    finish_reason: str | None = None
+
+
+def maybe_quantize_kv_cache(
+    prompt_cache: list[Any],
+    quantized_kv_start: int,
+    kv_group_size: int,
+    kv_bits: int | None,
+) -> None:
+    """Quantize KV cache entries if needed."""
+    if kv_bits is None:
+        return
+    for e, c in enumerate(prompt_cache):
+        if (
+            hasattr(c, "to_quantized")
+            and hasattr(c, "offset")
+            and c.offset >= quantized_kv_start
+        ):
+            prompt_cache[e] = c.to_quantized(group_size=kv_group_size, bits=kv_bits)
+
+
+class ModelWithHiddenStates(nn.Module):
+    """Wrapper to extract hidden states before lm_head.
+
+    This wrapper allows capturing the hidden states from the transformer
+    layers before the final lm_head projection, which is needed for MTP.
+    """
+
+    def __init__(self, base_model: nn.Module) -> None:
+        super().__init__()
+        self._base = base_model
+
+    def forward_with_hidden(
+        self,
+        inputs: mx.array,
+        model_cache: list[Any] | None = None,
+    ) -> tuple[mx.array, mx.array]:
+        """Forward pass that returns both logits and hidden states.
+
+        Args:
+            inputs: Input token ids
+            model_cache: KV cache
+
+        Returns:
+            Tuple of (logits, hidden_states)
+        """
+        # Call the inner model (transformer layers + norm)
+        hidden: mx.array = self._base.model(inputs, model_cache)
+        # Get logits from lm_head
+        logits: mx.array = self._base.lm_head(hidden)
+        return logits, hidden
+
+    def forward(
+        self,
+        inputs: mx.array,
+        model_cache: list[Any] | None = None,
+    ) -> mx.array:
+        """Standard forward pass returning only logits."""
+        return cast(mx.array, self._base(inputs, cache=model_cache))
+
+    @property
+    def layers(self) -> list[nn.Module]:
+        """Access layers for cache creation."""
+        return cast(list[nn.Module], self._base.layers)
+
+
+def mtp_speculative_generate_step(
+    prompt: mx.array,
+    model: nn.Module,
+    mtp_module: MTPModule,
+    *,
+    num_draft_tokens: int = 1,
+    max_tokens: int = 256,
+    sampler: Callable[[mx.array], mx.array] | None = None,
+    logits_processors: list[Callable[[mx.array, mx.array], mx.array]] | None = None,
+    prompt_cache: list[Any] | None = None,
+    mtp_cache: KVCache | None = None,
+    prefill_step_size: int = 512,
+    kv_bits: int | None = None,
+    kv_group_size: int = 64,
+    quantized_kv_start: int = 0,
+) -> Generator[tuple[int, mx.array, bool], None, None]:
+    """MTP speculative decoding generator.
+
+    Unlike standard speculative decoding where the draft model only needs tokens,
+    MTP requires the hidden states from the main model. This generator:
+
+    1. Runs the main model to get logits AND hidden states
+    2. Uses MTP module with hidden state + sampled token to predict next token
+    3. Verifies MTP predictions with the main model
+    4. Accepts/rejects based on matching
+
+    Args:
+        prompt: The input prompt as token ids
+        model: The main model (must support return_hidden=True)
+        mtp_module: The MTP module for draft prediction
+        num_draft_tokens: Number of tokens to draft (typically 1 for MTP)
+        max_tokens: Maximum number of tokens to generate
+        sampler: Optional sampler function for token selection
+        logits_processors: Optional list of logits processors
+        prompt_cache: KV cache for the main model
+        mtp_cache: KV cache for the MTP module
+        prefill_step_size: Step size for prompt processing
+        kv_bits: Bits for KV cache quantization
+        kv_group_size: Group size for KV cache quantization
+        quantized_kv_start: Step to begin cache quantization
+
+    Yields:
+        Tuple of (token, logprobs, from_draft)
+    """
+    y = prompt.astype(mx.uint32)
+    prev_tokens: mx.array | None = None
+
+    # Wrap model to get hidden states
+    wrapped_model = (
+        model
+        if isinstance(model, ModelWithHiddenStates)
+        else ModelWithHiddenStates(model)
+    )
+
+    # Create caches if needed
+    if prompt_cache is None:
+        prompt_cache = cache.make_prompt_cache(model)
+    if mtp_cache is None:
+        mtp_cache = KVCache()
+
+    final_sampler = (
+        sampler if sampler is not None else (lambda x: mx.argmax(x, axis=-1))
+    )
+
+    quantize_cache_fn = functools.partial(
+        maybe_quantize_kv_cache,
+        quantized_kv_start=quantized_kv_start,
+        kv_group_size=kv_group_size,
+        kv_bits=kv_bits,
+    )
+
+    def _process_and_sample(
+        tokens: mx.array | None,
+        logits: mx.array,
+    ) -> tuple[mx.array, mx.array]:
+        """Process logits and sample tokens."""
+        nonlocal logits_processors
+        processed_logits = logits
+        if logits_processors:
+            for processor in logits_processors:
+                processed_logits = processor(
+                    tokens if tokens is not None else mx.array([]), processed_logits
+                )
+
+        logprobs = processed_logits - mx.logsumexp(
+            processed_logits, axis=-1, keepdims=True
+        )
+        sampled = final_sampler(logprobs)
+        return sampled, logprobs
+
+    def _main_model_step_with_hidden(
+        input_y: mx.array,
+    ) -> tuple[mx.array, mx.array, mx.array]:
+        """Run main model step with hidden state return."""
+        nonlocal prev_tokens
+
+        with mx.stream(generation_stream):
+            logits, hidden = wrapped_model.forward_with_hidden(
+                input_y[None], prompt_cache
+            )
+            logits = logits[:, -1, :]
+            quantize_cache_fn(prompt_cache)
+
+            if logits_processors:
+                prev_tokens = (
+                    mx.concatenate([prev_tokens, input_y])
+                    if prev_tokens is not None
+                    else input_y
+                )
+
+            sampled, logprobs_result = _process_and_sample(prev_tokens, logits)
+            return sampled, logprobs_result.squeeze(0), hidden[:, -1:, :]
+
+    def _main_model_step(
+        input_y: mx.array,
+    ) -> tuple[mx.array, mx.array]:
+        """Run main model step without hidden state."""
+        nonlocal prev_tokens
+
+        with mx.stream(generation_stream):
+            logits = wrapped_model.forward(input_y[None], prompt_cache)
+            logits = logits[:, -1, :]
+            quantize_cache_fn(prompt_cache)
+
+            if logits_processors:
+                prev_tokens = (
+                    mx.concatenate([prev_tokens, input_y])
+                    if prev_tokens is not None
+                    else input_y
+                )
+
+            sampled, logprobs_result = _process_and_sample(prev_tokens, logits)
+            return sampled, logprobs_result.squeeze(0)
+
+    def _mtp_draft(
+        hidden_state: mx.array,
+        draft_token: mx.array,
+    ) -> tuple[mx.array, mx.array]:
+        """Generate draft token using MTP module."""
+        with mx.stream(generation_stream):
+            logits, new_hidden = mtp_module(
+                hidden_state,
+                draft_token,
+                cache=mtp_cache,
+            )
+            logits = logits[:, -1, :]
+            sampled, _ = _process_and_sample(None, logits)
+            return sampled, new_hidden
+
+    def _prefill(input_y: mx.array) -> mx.array:
+        """Prefill the prompt cache."""
+        result_y = input_y
+        while result_y.size > prefill_step_size:
+            _ = wrapped_model.forward(result_y[:prefill_step_size][None], prompt_cache)
+            quantize_cache_fn(prompt_cache)
+            mx.eval([c.state for c in prompt_cache])
+            result_y = result_y[prefill_step_size:]
+            mx.clear_cache()
+        return result_y
+
+    def _rewind_cache(num_draft: int, num_accept: int) -> None:
+        """Rewind caches after rejection."""
+        cache.trim_prompt_cache(prompt_cache, num_draft - num_accept)
+
+    # Prefill phase
+    with mx.stream(generation_stream):
+        y = _prefill(y)
+
+    ntoks = 0
+    num_draft = 0
+    n_accepted = 0
+    last_hidden: mx.array | None = None
+
+    try:
+        # Initial step to get first token and hidden state
+        sampled, logprobs, last_hidden = _main_model_step_with_hidden(y)
+        mx.eval(sampled, logprobs, last_hidden)
+
+        y = sampled
+        current_logprobs = logprobs
+
+        while ntoks < max_tokens:
+            # Draft phase: use MTP to predict next token
+            num_draft = min(max_tokens - ntoks - 1, num_draft_tokens)
+
+            if num_draft > 0 and last_hidden is not None:
+                # Use MTP to draft
+                draft_token, draft_hidden = _mtp_draft(last_hidden, y)
+                mx.eval(draft_token, draft_hidden)
+
+                # Verify with main model
+                # Feed the drafted token to main model
+                verify_input = mx.concatenate([y, draft_token.flatten()])
+                verify_sampled, verify_logprobs, new_hidden = (
+                    _main_model_step_with_hidden(verify_input)
+                )
+                mx.eval(verify_sampled, verify_logprobs, new_hidden)
+
+                # Check if draft matches verification
+                draft_token_val = int(draft_token.item())
+                verify_token_val = (
+                    int(verify_sampled[0].item())
+                    if verify_sampled.shape[0] > 1
+                    else int(verify_sampled.item())
+                )
+
+                # Yield the current token (not from draft)
+                ntoks += 1
+                yield int(y.item()), current_logprobs, False
+
+                if ntoks >= max_tokens:
+                    break
+
+                if draft_token_val == verify_token_val:
+                    # Draft accepted
+                    n_accepted += 1
+                    ntoks += 1
+                    draft_logprobs = (
+                        verify_logprobs[0]
+                        if verify_logprobs.ndim > 1
+                        else verify_logprobs
+                    )
+                    yield draft_token_val, draft_logprobs, True
+
+                    if ntoks >= max_tokens:
+                        break
+
+                    # Continue with the token after the draft
+                    y = (
+                        verify_sampled[-1:]
+                        if verify_sampled.ndim > 0 and verify_sampled.shape[0] > 1
+                        else verify_sampled
+                    )
+                    current_logprobs = (
+                        verify_logprobs[-1]
+                        if verify_logprobs.ndim > 1
+                        else verify_logprobs
+                    )
+                    last_hidden = new_hidden
+                else:
+                    # Draft rejected - rewind and use verified token
+                    _rewind_cache(1, 0)
+                    y = (
+                        verify_sampled[:1]
+                        if verify_sampled.ndim > 0 and verify_sampled.shape[0] > 1
+                        else verify_sampled
+                    )
+                    current_logprobs = (
+                        verify_logprobs[0]
+                        if verify_logprobs.ndim > 1
+                        else verify_logprobs
+                    )
+                    last_hidden = (
+                        new_hidden[:, :1, :] if new_hidden is not None else None
+                    )
+            else:
+                # No drafting, just do normal generation
+                ntoks += 1
+                yield int(y.item()), current_logprobs, False
+
+                if ntoks >= max_tokens:
+                    break
+
+                sampled, logprobs, last_hidden = _main_model_step_with_hidden(y)
+                mx.eval(sampled, logprobs, last_hidden)
+
+                y = sampled
+                current_logprobs = logprobs
+
+            if ntoks % 256 == 0:
+                mx.clear_cache()
+
+    finally:
+        _rewind_cache(num_draft, n_accepted)
+
+
+def mtp_speculative_generate(
+    model: nn.Module,
+    mtp_module: MTPModule,
+    tokenizer: TokenizerWrapper,
+    prompt: str | mx.array | list[int],
+    max_tokens: int = 256,
+    sampler: Callable[[mx.array], mx.array] | None = None,
+    logits_processors: list[Callable[[mx.array, mx.array], mx.array]] | None = None,
+    prompt_cache: list[Any] | None = None,
+    num_draft_tokens: int = 1,
+    prefill_step_size: int = 512,
+    kv_group_size: int = 64,
+    kv_bits: int | None = None,
+) -> Generator[MTPGenerationResponse, None, None]:
+    """High-level MTP speculative generation with text output.
+
+    Args:
+        model: The main model
+        mtp_module: The MTP module for draft prediction
+        tokenizer: Tokenizer for encoding/decoding
+        prompt: Input prompt (string, array, or token list)
+        max_tokens: Maximum tokens to generate
+        sampler: Optional sampler function
+        logits_processors: Optional logits processors
+        prompt_cache: Optional KV cache
+        num_draft_tokens: Number of draft tokens
+        prefill_step_size: Prefill step size
+        kv_group_size: KV group size
+        kv_bits: KV bits
+
+    Yields:
+        MTPGenerationResponse objects with text and metadata
+    """
+    if not isinstance(prompt, mx.array):
+        if isinstance(prompt, str):
+            bos_token = getattr(tokenizer, "bos_token", None)
+            add_special_tokens = bos_token is None or not prompt.startswith(
+                str(bos_token)
+            )
+            encoded: list[int] = tokenizer.encode(
+                prompt, add_special_tokens=add_special_tokens
+            )
+            prompt = mx.array(encoded)
+        else:
+            prompt = mx.array(prompt)
+
+    detokenizer = tokenizer.detokenizer
+    eos_token_ids: list[int] = getattr(tokenizer, "eos_token_ids", [])
+
+    token_generator = mtp_speculative_generate_step(
+        prompt,
+        model,
+        mtp_module,
+        max_tokens=max_tokens,
+        sampler=sampler,
+        logits_processors=logits_processors,
+        prompt_cache=prompt_cache,
+        num_draft_tokens=num_draft_tokens,
+        prefill_step_size=prefill_step_size,
+        kv_group_size=kv_group_size,
+        kv_bits=kv_bits,
+    )
+
+    tic = time.perf_counter()
+    prompt_tps = 0.0
+    token = 0
+    logprobs: mx.array = mx.array([0.0])
+    from_draft = False
+    n = 0
+
+    for n, (token, logprobs, from_draft) in enumerate(token_generator):
+        if n == 0:
+            prompt_time = time.perf_counter() - tic
+            prompt_tps = float(prompt.size) / prompt_time
+            tic = time.perf_counter()
+
+        if token in eos_token_ids:
+            break
+
+        detokenizer.add_token(token)
+        if (n + 1) == max_tokens:
+            break
+
+        yield MTPGenerationResponse(
+            text=str(detokenizer.last_segment),
+            token=token,
+            logprobs=logprobs,
+            from_draft=from_draft,
+            prompt_tokens=int(prompt.size),
+            prompt_tps=prompt_tps,
+            generation_tokens=n + 1,
+            generation_tps=(n + 1) / (time.perf_counter() - tic),
+            peak_memory=mx.get_peak_memory() / 1e9,
+            finish_reason=None,
+        )
+
+    detokenizer.finalize()
+    yield MTPGenerationResponse(
+        text=str(detokenizer.last_segment),
+        token=token,
+        logprobs=logprobs,
+        from_draft=from_draft,
+        prompt_tokens=int(prompt.size),
+        prompt_tps=prompt_tps,
+        generation_tokens=n + 1,
+        generation_tps=(n + 1) / (time.perf_counter() - tic),
+        peak_memory=mx.get_peak_memory() / 1e9,
+        finish_reason="stop" if token in eos_token_ids else "length",
+    )

src/exo/worker/engines/mlx/mtp/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for MTP module."""

src/exo/worker/engines/mlx/mtp/tests/test_mtp_module.py

@@ -0,0 +1,412 @@
+"""Unit tests for MTP module components."""
+
+import mlx.core as mx
+import mlx.nn as nn
+import pytest
+
+from exo.worker.engines.mlx.mtp.module import (
+    MTP_LAYER_INDEX,
+    MTPModule,
+    MTPTransformerBlock,
+    extract_mtp_weights,
+    load_mtp_weights_into_module,
+)
+
+
+class MockModelArgs:
+    """Mock ModelArgs for testing without importing deepseek_v3."""
+
+    def __init__(
+        self,
+        hidden_size: int = 256,
+        intermediate_size: int = 512,
+        num_attention_heads: int = 4,
+        num_key_value_heads: int = 4,
+        rms_norm_eps: float = 1e-6,
+        vocab_size: int = 1000,
+        q_lora_rank: int | None = None,
+        kv_lora_rank: int = 64,
+        qk_rope_head_dim: int = 16,
+        v_head_dim: int = 32,
+        qk_nope_head_dim: int = 32,
+        rope_theta: float = 10000.0,
+        rope_scaling: dict | None = None,
+        attention_bias: bool = False,
+        max_position_embeddings: int = 2048,
+    ):
+        self.hidden_size = hidden_size
+        self.intermediate_size = intermediate_size
+        self.num_attention_heads = num_attention_heads
+        self.num_key_value_heads = num_key_value_heads
+        self.rms_norm_eps = rms_norm_eps
+        self.vocab_size = vocab_size
+        self.q_lora_rank = q_lora_rank
+        self.kv_lora_rank = kv_lora_rank
+        self.qk_rope_head_dim = qk_rope_head_dim
+        self.v_head_dim = v_head_dim
+        self.qk_nope_head_dim = qk_nope_head_dim
+        self.rope_theta = rope_theta
+        self.rope_scaling = rope_scaling
+        self.attention_bias = attention_bias
+        self.max_position_embeddings = max_position_embeddings
+
+
+class TestExtractMTPWeights:
+    """Tests for extract_mtp_weights function."""
+
+    def test_extracts_layer_61_weights(self) -> None:
+        """Should extract only layer 61 weights."""
+        weights = {
+            "model.layers.60.self_attn.weight": mx.zeros((10, 10)),
+            "model.layers.61.enorm.weight": mx.ones((10,)),
+            "model.layers.61.hnorm.weight": mx.ones((10,)) * 2,
+            "model.layers.61.eh_proj.weight": mx.ones((10, 20)),
+            "model.layers.62.self_attn.weight": mx.zeros((10, 10)),
+            "model.embed_tokens.weight": mx.zeros((100, 10)),
+        }
+
+        mtp_weights = extract_mtp_weights(weights)
+
+        assert len(mtp_weights) == 3
+        assert "enorm.weight" in mtp_weights
+        assert "hnorm.weight" in mtp_weights
+        assert "eh_proj.weight" in mtp_weights
+        # Check values are preserved
+        assert mx.allclose(mtp_weights["enorm.weight"], mx.ones((10,)))
+        assert mx.allclose(mtp_weights["hnorm.weight"], mx.ones((10,)) * 2)
+
+    def test_returns_empty_dict_when_no_layer_61(self) -> None:
+        """Should return empty dict when layer 61 doesn't exist."""
+        weights = {
+            "model.layers.0.self_attn.weight": mx.zeros((10, 10)),
+            "model.layers.60.self_attn.weight": mx.zeros((10, 10)),
+        }
+
+        mtp_weights = extract_mtp_weights(weights)
+
+        assert len(mtp_weights) == 0
+
+    def test_handles_nested_layer_61_weights(self) -> None:
+        """Should handle nested weight paths like self_attn.q_proj.weight."""
+        weights = {
+            f"model.layers.{MTP_LAYER_INDEX}.self_attn.q_a_proj.weight": mx.zeros(
+                (10, 10)
+            ),
+            f"model.layers.{MTP_LAYER_INDEX}.mlp.gate_proj.weight": mx.zeros((20, 10)),
+        }
+
+        mtp_weights = extract_mtp_weights(weights)
+
+        assert "self_attn.q_a_proj.weight" in mtp_weights
+        assert "mlp.gate_proj.weight" in mtp_weights
+
+
+class TestMTPTransformerBlock:
+    """Tests for MTPTransformerBlock."""
+
+    @pytest.fixture
+    def config(self) -> MockModelArgs:
+        return MockModelArgs(
+            hidden_size=64, intermediate_size=128, num_attention_heads=2
+        )
+
+    def test_forward_shape(self, config: MockModelArgs) -> None:
+        """Forward pass should preserve input shape."""
+        # Skip if deepseek_v3 imports fail (CI without mlx_lm)
+        pytest.importorskip("mlx_lm.models.deepseek_v3")
+
+        block = MTPTransformerBlock(config)  # type: ignore[arg-type]
+        x = mx.random.normal((1, 5, config.hidden_size))
+
+        output = block(x)
+
+        assert output.shape == x.shape
+
+    def test_forward_with_mask(self, config: MockModelArgs) -> None:
+        """Forward pass should work with attention mask."""
+        pytest.importorskip("mlx_lm.models.deepseek_v3")
+
+        block = MTPTransformerBlock(config)  # type: ignore[arg-type]
+        x = mx.random.normal((1, 5, config.hidden_size))
+        # Create causal mask
+        mask = mx.triu(mx.full((5, 5), float("-inf")), k=1)
+
+        output = block(x, mask=mask)
+
+        assert output.shape == x.shape
+
+
+class TestMTPModule:
+    """Tests for MTPModule."""
+
+    @pytest.fixture
+    def config(self) -> MockModelArgs:
+        return MockModelArgs(
+            hidden_size=64,
+            intermediate_size=128,
+            num_attention_heads=2,
+            vocab_size=100,
+        )
+
+    @pytest.fixture
+    def shared_components(
+        self, config: MockModelArgs
+    ) -> tuple[nn.Embedding, nn.Linear, nn.RMSNorm]:
+        embedding = nn.Embedding(config.vocab_size, config.hidden_size)
+        lm_head = nn.Linear(config.hidden_size, config.vocab_size, bias=False)
+        output_norm = nn.RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+        return embedding, lm_head, output_norm
+
+    def test_initialization(
+        self,
+        config: MockModelArgs,
+        shared_components: tuple[nn.Embedding, nn.Linear, nn.RMSNorm],
+    ) -> None:
+        """MTPModule should initialize with correct components."""
+        pytest.importorskip("mlx_lm.models.deepseek_v3")
+
+        embedding, lm_head, output_norm = shared_components
+        mtp = MTPModule(
+            config=config,  # type: ignore[arg-type]
+            shared_embedding=embedding,
+            shared_lm_head=lm_head,
+            output_norm=output_norm,
+        )
+
+        assert mtp.hnorm is not None
+        assert mtp.enorm is not None
+        assert mtp.eh_proj is not None
+        assert mtp.transformer_block is not None
+
+    def test_forward_output_shapes(
+        self,
+        config: MockModelArgs,
+        shared_components: tuple[nn.Embedding, nn.Linear, nn.RMSNorm],
+    ) -> None:
+        """Forward pass should return correct output shapes."""
+        pytest.importorskip("mlx_lm.models.deepseek_v3")
+
+        embedding, lm_head, output_norm = shared_components
+        mtp = MTPModule(
+            config=config,  # type: ignore[arg-type]
+            shared_embedding=embedding,
+            shared_lm_head=lm_head,
+            output_norm=output_norm,
+        )
+
+        batch_size = 2
+        seq_len = 1
+        hidden_state = mx.random.normal((batch_size, seq_len, config.hidden_size))
+        draft_token = mx.array([[5], [10]])  # [batch, seq_len]
+
+        logits, new_hidden = mtp(hidden_state, draft_token)
+
+        assert logits.shape == (batch_size, seq_len, config.vocab_size)
+        assert new_hidden.shape == (batch_size, seq_len, config.hidden_size)
+
+    def test_shares_embedding_and_lm_head(
+        self,
+        config: MockModelArgs,
+        shared_components: tuple[nn.Embedding, nn.Linear, nn.RMSNorm],
+    ) -> None:
+        """MTPModule should use shared embedding and lm_head."""
+        pytest.importorskip("mlx_lm.models.deepseek_v3")
+
+        embedding, lm_head, output_norm = shared_components
+        mtp = MTPModule(
+            config=config,  # type: ignore[arg-type]
+            shared_embedding=embedding,
+            shared_lm_head=lm_head,
+            output_norm=output_norm,
+        )
+
+        # Verify they're the same objects
+        assert mtp._shared_embedding is embedding
+        assert mtp._shared_lm_head is lm_head
+        assert mtp._output_norm is output_norm
+
+
+class TestLoadMTPWeights:
+    """Tests for load_mtp_weights_into_module."""
+
+    @pytest.fixture
+    def config(self) -> MockModelArgs:
+        return MockModelArgs(
+            hidden_size=64,
+            intermediate_size=128,
+            num_attention_heads=2,
+            vocab_size=100,
+        )
+
+    def test_loads_norm_weights(self, config: MockModelArgs) -> None:
+        """Should load enorm and hnorm weights."""
+        pytest.importorskip("mlx_lm.models.deepseek_v3")
+
+        embedding = nn.Embedding(config.vocab_size, config.hidden_size)
+        lm_head = nn.Linear(config.hidden_size, config.vocab_size, bias=False)
+        output_norm = nn.RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+
+        mtp = MTPModule(
+            config=config,  # type: ignore[arg-type]
+            shared_embedding=embedding,
+            shared_lm_head=lm_head,
+            output_norm=output_norm,
+        )
+
+        # Create test weights
+        test_enorm = mx.ones((config.hidden_size,)) * 3.0
+        test_hnorm = mx.ones((config.hidden_size,)) * 5.0
+        mtp_weights = {
+            "enorm.weight": test_enorm,
+            "hnorm.weight": test_hnorm,
+        }
+
+        load_mtp_weights_into_module(mtp, mtp_weights)
+
+        assert mx.allclose(mtp.enorm.weight, test_enorm)
+        assert mx.allclose(mtp.hnorm.weight, test_hnorm)
+
+
+class TestSanitizePatch:
+    """Tests for the sanitize patching logic."""
+
+    def test_patch_preserves_layer_61(self) -> None:
+        """Patching sanitize should preserve layer 61 weights."""
+        from exo.worker.engines.mlx.utils_mlx import (
+            _patch_deepseek_sanitize_for_mtp,
+            _restore_deepseek_sanitize,
+        )
+
+        deepseek_v3 = pytest.importorskip("mlx_lm.models.deepseek_v3")
+        model_cls = deepseek_v3.Model
+
+        # Get original sanitize behavior
+        original_sanitize = model_cls.sanitize
+
+        try:
+            # Apply patch
+            _patch_deepseek_sanitize_for_mtp()
+
+            # Note: we can't easily test the full sanitize without a real model
+            # This test verifies the patch is applied
+            assert model_cls.sanitize is not original_sanitize
+
+        finally:
+            _restore_deepseek_sanitize()
+            # Verify restore worked
+            assert model_cls.sanitize is original_sanitize
+
+    def test_restore_sanitize(self) -> None:
+        """Restoring sanitize should return to original behavior."""
+        from exo.worker.engines.mlx.utils_mlx import (
+            _patch_deepseek_sanitize_for_mtp,
+            _restore_deepseek_sanitize,
+        )
+
+        deepseek_v3 = pytest.importorskip("mlx_lm.models.deepseek_v3")
+        model_cls = deepseek_v3.Model
+
+        original_sanitize = model_cls.sanitize
+
+        _patch_deepseek_sanitize_for_mtp()
+        assert model_cls.sanitize is not original_sanitize
+
+        _restore_deepseek_sanitize()
+        assert model_cls.sanitize is original_sanitize
+
+    def test_double_patch_is_safe(self) -> None:
+        """Calling patch twice should be safe (idempotent)."""
+        from exo.worker.engines.mlx.utils_mlx import (
+            _patch_deepseek_sanitize_for_mtp,
+            _restore_deepseek_sanitize,
+        )
+
+        deepseek_v3 = pytest.importorskip("mlx_lm.models.deepseek_v3")
+        model_cls = deepseek_v3.Model
+
+        original_sanitize = model_cls.sanitize
+
+        try:
+            _patch_deepseek_sanitize_for_mtp()
+            patched_sanitize = model_cls.sanitize
+
+            # Patch again - should be no-op
+            _patch_deepseek_sanitize_for_mtp()
+            assert model_cls.sanitize is patched_sanitize
+
+        finally:
+            _restore_deepseek_sanitize()
+            assert model_cls.sanitize is original_sanitize
+
+
+class TestModelIdDetection:
+    """Tests for DeepSeek V3 model ID detection."""
+
+    def test_detects_deepseek_v3(self) -> None:
+        """Should detect DeepSeek V3 model IDs."""
+        from exo.worker.engines.mlx.utils_mlx import _might_be_deepseek_v3
+
+        assert _might_be_deepseek_v3("deepseek-ai/DeepSeek-V3")
+        assert _might_be_deepseek_v3("deepseek-ai/deepseek-v3-base")
+        assert _might_be_deepseek_v3("mlx-community/DeepSeek-V3-4bit")
+
+    def test_detects_deepseek_r1(self) -> None:
+        """Should detect DeepSeek R1 model IDs (also uses MTP)."""
+        from exo.worker.engines.mlx.utils_mlx import _might_be_deepseek_v3
+
+        assert _might_be_deepseek_v3("deepseek-ai/DeepSeek-R1")
+        assert _might_be_deepseek_v3("mlx-community/DeepSeek-R1-4bit")
+
+    def test_rejects_non_deepseek(self) -> None:
+        """Should reject non-DeepSeek model IDs."""
+        from exo.worker.engines.mlx.utils_mlx import _might_be_deepseek_v3
+
+        assert not _might_be_deepseek_v3("meta-llama/Llama-3-70B")
+        assert not _might_be_deepseek_v3("mistralai/Mixtral-8x7B")
+        assert not _might_be_deepseek_v3("deepseek-ai/DeepSeek-V2")  # V2, not V3
+
+    def test_case_insensitive(self) -> None:
+        """Detection should be case insensitive."""
+        from exo.worker.engines.mlx.utils_mlx import _might_be_deepseek_v3
+
+        assert _might_be_deepseek_v3("DEEPSEEK-AI/DEEPSEEK-V3")
+        assert _might_be_deepseek_v3("DeepSeek-AI/deepseek-v3")
+
+
+class TestFlattenParams:
+    """Tests for parameter flattening utility."""
+
+    def test_flattens_nested_dict(self) -> None:
+        """Should flatten nested parameter dict."""
+        from exo.worker.engines.mlx.utils_mlx import _flatten_params
+
+        params = {
+            "model": {
+                "layers": {
+                    "0": {
+                        "weight": mx.zeros((10,)),
+                    }
+                },
+                "embed": mx.ones((5,)),
+            }
+        }
+
+        flat = _flatten_params(params)
+
+        assert "model.layers.0.weight" in flat
+        assert "model.embed" in flat
+        assert mx.allclose(flat["model.layers.0.weight"], mx.zeros((10,)))
+        assert mx.allclose(flat["model.embed"], mx.ones((5,)))
+
+    def test_handles_flat_dict(self) -> None:
+        """Should handle already-flat dict."""
+        from exo.worker.engines.mlx.utils_mlx import _flatten_params
+
+        params = {
+            "weight": mx.zeros((10,)),
+            "bias": mx.ones((10,)),
+        }
+
+        flat = _flatten_params(params)
+
+        assert flat == params

src/exo/worker/engines/mlx/mtp/tests/test_speculative_decode.py

@@ -0,0 +1,253 @@
+"""Unit tests for MTP speculative decoding."""
+
+import mlx.core as mx
+import mlx.nn as nn
+import pytest
+
+from exo.worker.engines.mlx.mtp.speculative_decode import (
+    ModelWithHiddenStates,
+    maybe_quantize_kv_cache,
+)
+
+
+class MockModel(nn.Module):
+    """Mock model for testing speculative decoding."""
+
+    def __init__(self, hidden_size: int = 64, vocab_size: int = 100) -> None:
+        super().__init__()
+        self.hidden_size = hidden_size
+        self.vocab_size = vocab_size
+
+        # Create simple model components
+        self.model = MockInnerModel(hidden_size)
+        self.lm_head = nn.Linear(hidden_size, vocab_size, bias=False)
+        self._layers = [nn.Linear(hidden_size, hidden_size) for _ in range(3)]
+
+    def __call__(
+        self,
+        inputs: mx.array,
+        cache: list | None = None,
+    ) -> mx.array:
+        hidden = self.model(inputs, cache)
+        return self.lm_head(hidden)
+
+    @property
+    def layers(self) -> list[nn.Module]:
+        return self._layers
+
+
+class MockInnerModel(nn.Module):
+    """Mock inner model (like DeepseekV3Model)."""
+
+    def __init__(self, hidden_size: int) -> None:
+        super().__init__()
+        self.embed_tokens = nn.Embedding(100, hidden_size)
+        self.norm = nn.RMSNorm(hidden_size)
+
+    def __call__(
+        self,
+        inputs: mx.array,
+        cache: list | None = None,
+    ) -> mx.array:
+        # Simple embedding + norm
+        embedded = self.embed_tokens(inputs)
+        return self.norm(embedded)
+
+
+class TestModelWithHiddenStates:
+    """Tests for ModelWithHiddenStates wrapper."""
+
+    @pytest.fixture
+    def mock_model(self) -> MockModel:
+        return MockModel(hidden_size=64, vocab_size=100)
+
+    def test_forward_returns_logits(self, mock_model: MockModel) -> None:
+        """Standard forward should return logits."""
+        wrapped = ModelWithHiddenStates(mock_model)
+        inputs = mx.array([[1, 2, 3]])
+
+        logits = wrapped.forward(inputs)
+
+        assert logits.shape == (1, 3, mock_model.vocab_size)
+
+    def test_forward_with_hidden_returns_tuple(self, mock_model: MockModel) -> None:
+        """Forward with hidden should return (logits, hidden)."""
+        wrapped = ModelWithHiddenStates(mock_model)
+        inputs = mx.array([[1, 2, 3]])
+
+        logits, hidden = wrapped.forward_with_hidden(inputs)
+
+        assert logits.shape == (1, 3, mock_model.vocab_size)
+        assert hidden.shape == (1, 3, mock_model.hidden_size)
+
+    def test_layers_property(self, mock_model: MockModel) -> None:
+        """Should expose layers property from base model."""
+        wrapped = ModelWithHiddenStates(mock_model)
+
+        assert wrapped.layers == mock_model.layers
+        assert len(wrapped.layers) == 3
+
+
+class TestMaybeQuantizeKVCache:
+    """Tests for KV cache quantization."""
+
+    def test_no_quantization_when_bits_none(self) -> None:
+        """Should not quantize when kv_bits is None."""
+        cache = [MockCache(offset=100)]
+
+        maybe_quantize_kv_cache(
+            cache,
+            quantized_kv_start=50,
+            kv_group_size=64,
+            kv_bits=None,
+        )
+
+        # Cache should be unchanged
+        assert not hasattr(cache[0], "quantized")
+
+    def test_respects_quantized_kv_start(self) -> None:
+        """Should only quantize caches past the start threshold."""
+        cache_below = MockCache(offset=30)
+        cache_above = MockCache(offset=100)
+        caches = [cache_below, cache_above]
+
+        maybe_quantize_kv_cache(
+            caches,
+            quantized_kv_start=50,
+            kv_group_size=64,
+            kv_bits=4,
+        )
+
+        # Only cache_above should be quantized
+        assert not getattr(cache_below, "was_quantized", False)
+        assert getattr(caches[1], "was_quantized", False)
+
+
+class MockCache:
+    """Mock KV cache for testing."""
+
+    def __init__(self, offset: int = 0) -> None:
+        self.offset = offset
+        self.was_quantized = False
+
+    def to_quantized(self, group_size: int, bits: int) -> "MockCache":
+        quantized = MockCache(self.offset)
+        quantized.was_quantized = True
+        return quantized
+
+
+class TestSpeculativeDecodingLogic:
+    """Tests for the core speculative decoding logic."""
+
+    def test_draft_acceptance_identical_tokens(self) -> None:
+        """When draft matches verification, both should be accepted."""
+        # This tests the logic, not the full generator
+        draft_token = 42
+        verify_token = 42
+
+        accepted = draft_token == verify_token
+        assert accepted
+
+    def test_draft_rejection_different_tokens(self) -> None:
+        """When draft differs from verification, draft should be rejected."""
+        draft_token = 42
+        verify_token = 99
+
+        accepted = draft_token == verify_token
+        assert not accepted
+
+
+class TestMTPGenerationResponse:
+    """Tests for MTPGenerationResponse dataclass."""
+
+    def test_response_creation(self) -> None:
+        """Should create response with all fields."""
+        from exo.worker.engines.mlx.mtp.speculative_decode import MTPGenerationResponse
+
+        response = MTPGenerationResponse(
+            text="Hello",
+            token=42,
+            logprobs=mx.array([0.1, 0.2]),
+            from_draft=True,
+            prompt_tokens=10,
+            prompt_tps=100.0,
+            generation_tokens=5,
+            generation_tps=50.0,
+            peak_memory=1.5,
+            finish_reason=None,
+        )
+
+        assert response.text == "Hello"
+        assert response.token == 42
+        assert response.from_draft is True
+        assert response.finish_reason is None
+
+    def test_response_with_finish_reason(self) -> None:
+        """Should handle finish_reason."""
+        from exo.worker.engines.mlx.mtp.speculative_decode import MTPGenerationResponse
+
+        response = MTPGenerationResponse(
+            text="",
+            token=0,
+            logprobs=mx.array([0.0]),
+            from_draft=False,
+            prompt_tokens=10,
+            prompt_tps=100.0,
+            generation_tokens=100,
+            generation_tps=50.0,
+            peak_memory=1.5,
+            finish_reason="length",
+        )
+
+        assert response.finish_reason == "length"
+
+
+class TestIntegration:
+    """Integration tests for the full MTP pipeline."""
+
+    def test_mtp_module_with_mock_model(self) -> None:
+        """Test MTP module can be created and run with mock components."""
+        pytest.importorskip("mlx_lm.models.deepseek_v3")
+
+        from exo.worker.engines.mlx.mtp.module import MTPModule
+
+        # Create mock config
+        class MockConfig:
+            hidden_size = 64
+            intermediate_size = 128
+            num_attention_heads = 2
+            num_key_value_heads = 2
+            rms_norm_eps = 1e-6
+            q_lora_rank = None
+            kv_lora_rank = 32
+            qk_rope_head_dim = 8
+            v_head_dim = 16
+            qk_nope_head_dim = 16
+            rope_theta = 10000.0
+            rope_scaling = None
+            attention_bias = False
+            max_position_embeddings = 2048
+
+        config = MockConfig()
+        embedding = nn.Embedding(100, config.hidden_size)
+        lm_head = nn.Linear(config.hidden_size, 100, bias=False)
+        output_norm = nn.RMSNorm(config.hidden_size)
+
+        mtp = MTPModule(
+            config=config,  # type: ignore[arg-type]
+            shared_embedding=embedding,
+            shared_lm_head=lm_head,
+            output_norm=output_norm,
+        )
+
+        # Run forward pass
+        hidden = mx.random.normal((1, 1, config.hidden_size))
+        token = mx.array([[5]])
+
+        logits, new_hidden = mtp(hidden, token)
+
+        assert logits.shape == (1, 1, 100)
+        assert new_hidden.shape == (1, 1, config.hidden_size)
+        # Verify outputs are valid (not NaN)
+        assert not mx.any(mx.isnan(logits))
+        assert not mx.any(mx.isnan(new_hidden))

src/exo/worker/engines/mlx/utils_mlx.py

@@ -3,6 +3,7 @@ import os
 import resource
 import sys
 import time
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any, cast
 
@@ -27,6 +28,7 @@ from exo.shared.models.model_cards import ModelId
 from exo.worker.engines.mlx.constants import (
     CACHE_GROUP_SIZE,
     KV_CACHE_BITS,
+    MTP_ENABLED,
     TRUST_REMOTE_CODE,
 )
 
@@ -70,6 +72,67 @@ Group = mx.distributed.Group
 resource.setrlimit(resource.RLIMIT_NOFILE, (2048, 4096))
 
 
+# MTP (Multi-Token Prediction) support for DeepSeek V3
+MTP_LAYER_INDEX = 61
+_original_deepseek_sanitize: Callable[..., dict[str, Any]] | None = None
+
+
+def _is_deepseek_v3_model(model: nn.Module) -> bool:
+    """Check if the model is DeepSeek V3."""
+    return hasattr(model, "model") and isinstance(model.model, DeepseekV3Model)
+
+
+def _patch_deepseek_sanitize_for_mtp() -> None:
+    """Patch DeepSeek V3 Model.sanitize to preserve MTP layer weights.
+
+    The original sanitize() method filters out layer 61 (MTP layer) weights.
+    This patch keeps them so we can extract and use the MTP module.
+    """
+    global _original_deepseek_sanitize
+    from mlx_lm.models.deepseek_v3 import Model as DeepSeekV3Model
+
+    if _original_deepseek_sanitize is not None:
+        # Already patched
+        return
+
+    _original_deepseek_sanitize = DeepSeekV3Model.sanitize
+
+    def sanitize_with_mtp(
+        self: DeepSeekV3Model, weights: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Modified sanitize that keeps MTP layer weights."""
+        # First, call the original sanitize to handle all the weight transformations
+        # (dequantization, expert stacking, etc.)
+        if _original_deepseek_sanitize is None:
+            raise RuntimeError(
+                "_original_deepseek_sanitize is None - patch not applied correctly"
+            )
+        original_result: dict[str, Any] = _original_deepseek_sanitize(self, weights)
+
+        # Re-add the MTP layer weights that were filtered out
+        mtp_weights = {
+            k: v
+            for k, v in weights.items()
+            if k.startswith(f"model.layers.{MTP_LAYER_INDEX}")
+        }
+
+        return {**original_result, **mtp_weights}
+
+    DeepSeekV3Model.sanitize = sanitize_with_mtp
+
+
+def _restore_deepseek_sanitize() -> None:
+    """Restore the original DeepSeek V3 sanitize method."""
+    global _original_deepseek_sanitize
+    if _original_deepseek_sanitize is None:
+        return
+
+    from mlx_lm.models.deepseek_v3 import Model as DeepSeekV3Model
+
+    DeepSeekV3Model.sanitize = _original_deepseek_sanitize
+    _original_deepseek_sanitize = None
+
+
 # TODO: Test this
 #  ALSO https://github.com/exo-explore/exo/pull/233#discussion_r2549683673
 def get_weights_size(model_shard_meta: ShardMetadata) -> Memory:
@@ -205,31 +268,164 @@ def load_mlx_items(
     group: Group | None,
     on_timeout: TimeoutCallback | None = None,
 ) -> tuple[Model, TokenizerWrapper]:
-    if group is None:
-        logger.info(f"Single device used for {bound_instance.instance}")
-        model_path = build_model_path(bound_instance.bound_shard.model_card.model_id)
-        start_time = time.perf_counter()
-        model, _ = load_model(model_path, strict=True)
-        end_time = time.perf_counter()
-        logger.info(f"Time taken to load model: {(end_time - start_time):.2f}s")
-        tokenizer = get_tokenizer(model_path, bound_instance.bound_shard)
+    """Load MLX model and tokenizer.
 
-    else:
-        logger.info("Starting distributed init")
-        start_time = time.perf_counter()
-        model, tokenizer = shard_and_load(
-            bound_instance.bound_shard, group=group, on_timeout=on_timeout
-        )
-        end_time = time.perf_counter()
-        logger.info(
-            f"Time taken to shard and load model: {(end_time - start_time):.2f}s"
-        )
+    Returns:
+        Tuple of (model, tokenizer)
+    """
+    model_id = bound_instance.bound_shard.model_meta.model_id
+    mtp_module = None
+
+    # Patch sanitize for MTP if this might be DeepSeek V3
+    should_try_mtp = MTP_ENABLED and _might_be_deepseek_v3(model_id)
+    if should_try_mtp:
+        logger.info("Patching DeepSeek V3 sanitize for MTP weight preservation")
+        _patch_deepseek_sanitize_for_mtp()
+
+    try:
+        if group is None:
+            logger.info(f"Single device used for {bound_instance.instance}")
+            model_path = build_model_path(model_id)
+            start_time = time.perf_counter()
+            model, _ = load_model(model_path, strict=not should_try_mtp)
+            end_time = time.perf_counter()
+            logger.info(f"Time taken to load model: {(end_time - start_time):.2f}s")
+            tokenizer = get_tokenizer(model_path, bound_instance.bound_shard)
+
+        else:
+            logger.info("Starting distributed init")
+            start_time = time.perf_counter()
+            model, tokenizer = shard_and_load(
+                bound_instance.bound_shard, group=group, on_timeout=on_timeout
+            )
+            end_time = time.perf_counter()
+            logger.info(
+                f"Time taken to shard and load model: {(end_time - start_time):.2f}s"
+            )
+
+        # Extract MTP module if available
+        if should_try_mtp and _is_deepseek_v3_model(model):
+            mtp_module = _extract_mtp_module(model)
+            if mtp_module is not None:
+                logger.info("Successfully extracted MTP module from DeepSeek V3")
+
+    finally:
+        # Restore original sanitize
+        if should_try_mtp:
+            _restore_deepseek_sanitize()
 
     set_wired_limit_for_model(get_weights_size(bound_instance.bound_shard))
 
+    # Store MTP module on the model for later access
+    if mtp_module is not None:
+        model.mtp_module = mtp_module  # noqa: B010
+
     return cast(Model, model), tokenizer
 
 
+def _might_be_deepseek_v3(model_id: str) -> bool:
+    """Check if model ID suggests this might be DeepSeek V3."""
+    model_id_lower = model_id.lower()
+    return "deepseek" in model_id_lower and (
+        "v3" in model_id_lower or "r1" in model_id_lower
+    )
+
+
+def _flatten_params(
+    params: dict[str, Any],
+    prefix: str = "",
+) -> dict[str, mx.array]:
+    """Flatten nested parameter dict to flat dict with dot-separated keys."""
+    result: dict[str, mx.array] = {}
+    for key, value in params.items():
+        full_key = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, mx.array):
+            result[full_key] = value
+        elif isinstance(value, dict):
+            result.update(_flatten_params(value, full_key))
+    return result
+
+
+def _extract_mtp_module(model: nn.Module) -> Any | None:
+    """Extract MTP module from a loaded DeepSeek V3 model.
+
+    The MTP weights are stored in model.model.layers at index 61 (if preserved).
+    This function extracts them and creates an MTPModule.
+
+    Returns:
+        MTPModule if MTP weights were found and extracted, None otherwise.
+    """
+    from exo.worker.engines.mlx.mtp.module import (
+        MTPModule,
+        extract_mtp_weights,
+        load_mtp_weights_into_module,
+    )
+
+    try:
+        # Check if the model has the MTP layer
+        inner_model = getattr(model, "model", None)
+        if inner_model is None or not hasattr(inner_model, "layers"):
+            logger.debug("Model doesn't have expected structure for MTP extraction")
+            return None
+
+        layers: list[nn.Module] = inner_model.layers  # type: ignore[assignment]
+        if len(layers) <= MTP_LAYER_INDEX:
+            logger.debug(
+                f"Model has {len(layers)} layers, MTP layer {MTP_LAYER_INDEX} not found"
+            )
+            return None
+
+        # Get model config
+        config = getattr(model, "args", None)
+        if config is None:
+            logger.debug("Could not get model config for MTP module")
+            return None
+
+        # Create MTP module with shared weights
+        embed_tokens = getattr(inner_model, "embed_tokens", None)
+        lm_head = getattr(model, "lm_head", None)
+        norm = getattr(inner_model, "norm", None)
+
+        if embed_tokens is None or lm_head is None or norm is None:
+            logger.debug("Could not get required model components for MTP")
+            return None
+
+        mtp_module = MTPModule(
+            config=config,
+            shared_embedding=embed_tokens,
+            shared_lm_head=lm_head,
+            output_norm=norm,
+        )
+
+        # Extract MTP layer weights from the model's parameters
+        # The weights should be at model.model.layers.61.*
+        # model.parameters() returns a nested dict, we need to flatten it
+        raw_params: dict[str, Any] = dict(model.parameters())  # type: ignore[arg-type]
+        model_weights = _flatten_params(raw_params)
+        mtp_weights = extract_mtp_weights(model_weights)
+
+        if not mtp_weights:
+            logger.debug("No MTP weights found in model parameters")
+            return None
+
+        # Load weights into MTP module
+        load_mtp_weights_into_module(mtp_module, mtp_weights)
+
+        # Remove MTP layer from main model to avoid double computation
+        # Create new layers list without the MTP layer
+        new_layers = [layer for i, layer in enumerate(layers) if i != MTP_LAYER_INDEX]
+        inner_model.layers = new_layers  # noqa: B010
+
+        logger.info(
+            f"Extracted MTP module, main model now has {len(new_layers)} layers"
+        )
+        return mtp_module
+
+    except Exception as e:
+        logger.warning(f"Failed to extract MTP module: {e}")
+        return None
+
+
 def shard_and_load(
     shard_metadata: ShardMetadata,
     group: Group,

src/exo/worker/plan.py

@@ -291,14 +291,12 @@ def _pending_tasks(
             # I have a design point here; this is a state race in disguise as the task status doesn't get updated to completed fast enough
             # however, realistically the task status should be set to completed by the LAST runner, so this is a true race
             # the actual solution is somewhat deeper than this bypass - TODO!
-            # Also skip tasks in pending to prevent duplicate forwarding with continuous batching
-            if task.task_id in runner.completed or task.task_id in runner.pending:
+            if task.task_id in runner.completed:
                 continue
 
             # TODO: Check ordering aligns with MLX distributeds expectations.
 
-            # Allow forwarding tasks when runner is Ready or Running (for continuous batching)
-            if isinstance(runner.status, (RunnerReady, RunnerRunning)) and all(
+            if isinstance(runner.status, RunnerReady) and all(
                 isinstance(all_runners[global_runner_id], (RunnerReady, RunnerRunning))
                 for global_runner_id in runner.bound_instance.instance.shard_assignments.runner_to_shard
             ):

src/exo/worker/runner/runner.py

@@ -1,10 +1,18 @@
 import base64
-import gc
 import time
+from collections.abc import Generator
+from functools import cache
 from typing import Literal
 
 import mlx.core as mx
-from anyio import WouldBlock
+from mlx_lm.models.gpt_oss import Model as GptOssModel
+from mlx_lm.tokenizer_utils import TokenizerWrapper
+from openai_harmony import (  # pyright: ignore[reportMissingTypeStubs]
+    HarmonyEncodingName,
+    Role,
+    StreamableParser,
+    load_harmony_encoding,
+)
 
 from exo.shared.constants import EXO_MAX_CHUNK_SIZE
 from exo.shared.models.model_cards import ModelId, ModelTask
@@ -31,6 +39,7 @@ from exo.shared.types.tasks import (
 )
 from exo.shared.types.worker.instances import BoundInstance
 from exo.shared.types.worker.runner_response import (
+    GenerationResponse,
     ImageGenerationResponse,
     PartialImageResponse,
 )
@@ -57,10 +66,10 @@ from exo.worker.engines.image import (
     warmup_image_generator,
 )
 from exo.worker.engines.mlx import Model
-from exo.worker.engines.mlx.generator.batch_engine import BatchGenerationEngine
-from exo.worker.engines.mlx.generator.generate import warmup_inference
-from exo.worker.engines.mlx.generator.time_budget import TimeBudget
+from exo.worker.engines.mlx.generator.generate import mlx_generate, warmup_inference
 from exo.worker.engines.mlx.utils_mlx import (
+    apply_chat_template,
+    detect_thinking_prompt_suffix,
     initialize_mlx,
     load_mlx_items,
     mlx_force_oom,
@@ -78,6 +87,7 @@ def main(
         bound_instance.bound_runner_id,
         bound_instance.bound_shard,
     )
+    device_rank = shard_metadata.device_rank
     logger.info("hello from the runner")
     if getattr(shard_metadata, "immediate_exception", False):
         raise Exception("Fake exception - runner failed to spin up.")
@@ -89,491 +99,404 @@ def main(
     model: Model | DistributedImageModel | None = None
     tokenizer = None
     group = None
-    batch_engine: BatchGenerationEngine | None = None
-    pending_shutdown: Shutdown | None = None
 
     current_status: RunnerStatus = RunnerIdle()
-
-    def send_status(status: RunnerStatus) -> None:
-        event_sender.send(
-            RunnerStatusUpdated(runner_id=runner_id, runner_status=status)
-        )
-
     logger.info("runner created")
-    send_status(current_status)
-
-    def handle_task(task: Task, is_deferred: bool = False) -> bool:
-        nonlocal current_status, model, tokenizer, group, batch_engine, pending_shutdown
-
-        # For Shutdown, check if we need to defer BEFORE sending Running/Acknowledged
-        if (
-            isinstance(task, Shutdown)
-            and not is_deferred
-            and batch_engine is not None
-            and (batch_engine.has_active_requests or batch_engine.has_pending_inserts)
-        ):
-            logger.info("deferring shutdown until active requests complete")
-            pending_shutdown = task
-            return True
-
-        event_sender.send(
-            TaskStatusUpdated(task_id=task.task_id, task_status=TaskStatus.Running)
-        )
-        event_sender.send(TaskAcknowledged(task_id=task.task_id))
-
-        match task:
-            case ConnectToGroup() if isinstance(
-                current_status, (RunnerIdle, RunnerFailed)
-            ):
-                logger.info("runner connecting")
-                current_status = RunnerConnecting()
-                send_status(current_status)
-                group = initialize_mlx(bound_instance)
-
-                logger.info("runner connected")
-                current_status = RunnerConnected()
-                event_sender.send(
-                    TaskStatusUpdated(
-                        task_id=task.task_id, task_status=TaskStatus.Complete
-                    )
-                )
-                send_status(current_status)
-
-            case LoadModel() if (
-                isinstance(current_status, RunnerConnected) and group is not None
-            ) or (isinstance(current_status, RunnerIdle) and group is None):
-                current_status = RunnerLoading()
-                logger.info("runner loading")
-                send_status(current_status)
-
-                def on_model_load_timeout() -> None:
+    event_sender.send(
+        RunnerStatusUpdated(runner_id=runner_id, runner_status=current_status)
+    )
+    with task_receiver as tasks:
+        for task in tasks:
+            event_sender.send(
+                TaskStatusUpdated(task_id=task.task_id, task_status=TaskStatus.Running)
+            )
+            event_sender.send(TaskAcknowledged(task_id=task.task_id))
+            match task:
+                case ConnectToGroup() if isinstance(
+                    current_status, (RunnerIdle, RunnerFailed)
+                ):
+                    logger.info("runner connecting")
+                    current_status = RunnerConnecting()
                     event_sender.send(
                         RunnerStatusUpdated(
-                            runner_id=runner_id,
-                            runner_status=RunnerFailed(
-                                error_message="Model loading timed out"
-                            ),
+                            runner_id=runner_id, runner_status=current_status
                         )
                     )
-                    time.sleep(0.5)
+                    group = initialize_mlx(bound_instance)
 
-                if ModelTask.TextGeneration in shard_metadata.model_card.tasks:
-                    model, tokenizer = load_mlx_items(
-                        bound_instance, group, on_timeout=on_model_load_timeout
-                    )
-                elif (
-                    ModelTask.TextToImage in shard_metadata.model_card.tasks
-                    or ModelTask.ImageToImage in shard_metadata.model_card.tasks
-                ):
-                    model = initialize_image_model(bound_instance)
-                else:
-                    raise ValueError(
-                        f"Unknown model task(s): {shard_metadata.model_card.tasks}"
+                    logger.info("runner connected")
+                    current_status = RunnerConnected()
+
+                # we load the model if it's connected with a group, or idle without a group. we should never tell a model to connect if it doesn't need to
+                case LoadModel() if (
+                    isinstance(current_status, RunnerConnected) and group is not None
+                ) or (isinstance(current_status, RunnerIdle) and group is None):
+                    current_status = RunnerLoading()
+                    logger.info("runner loading")
+                    event_sender.send(
+                        RunnerStatusUpdated(
+                            runner_id=runner_id, runner_status=current_status
+                        )
                     )
 
-                current_status = RunnerLoaded()
-                logger.info("runner loaded")
-                event_sender.send(
-                    TaskStatusUpdated(
-                        task_id=task.task_id, task_status=TaskStatus.Complete
-                    )
-                )
-                send_status(current_status)
+                    def on_model_load_timeout() -> None:
+                        event_sender.send(
+                            RunnerStatusUpdated(
+                                runner_id=runner_id,
+                                runner_status=RunnerFailed(
+                                    error_message="Model loading timed out"
+                                ),
+                            )
+                        )
+                        time.sleep(0.5)
 
-            case StartWarmup() if isinstance(current_status, RunnerLoaded):
-                assert model is not None
-                current_status = RunnerWarmingUp()
-                logger.info("runner warming up")
-                send_status(current_status)
-
-                logger.info(f"warming up inference for instance: {instance}")
-                if ModelTask.TextGeneration in shard_metadata.model_card.tasks:
-                    assert not isinstance(model, DistributedImageModel)
-                    assert tokenizer is not None
-                    toks = warmup_inference(model=model, tokenizer=tokenizer)
-                    logger.info(f"warmed up by generating {toks} tokens")
-                    logger.info(
-                        f"runner initialized in {time.time() - setup_start_time} seconds"
-                    )
-
-                    batch_engine = BatchGenerationEngine(
-                        model=model, tokenizer=tokenizer, group=group
-                    )
-                elif (
-                    ModelTask.TextToImage in shard_metadata.model_card.tasks
-                    or ModelTask.ImageToImage in shard_metadata.model_card.tasks
-                ):
-                    assert isinstance(model, DistributedImageModel)
-                    image = warmup_image_generator(model=model)
-                    if image is not None:
-                        logger.info(f"warmed up by generating {image.size} image")
+                    if ModelTask.TextGeneration in shard_metadata.model_card.tasks:
+                        model, tokenizer = load_mlx_items(
+                            bound_instance, group, on_timeout=on_model_load_timeout
+                        )
+                    elif (
+                        ModelTask.TextToImage in shard_metadata.model_card.tasks
+                        or ModelTask.ImageToImage in shard_metadata.model_card.tasks
+                    ):
+                        model = initialize_image_model(bound_instance)
                     else:
-                        logger.info("warmup completed (non-primary node)")
-
-                current_status = RunnerReady()
-                logger.info("runner ready")
-                event_sender.send(
-                    TaskStatusUpdated(
-                        task_id=task.task_id, task_status=TaskStatus.Complete
-                    )
-                )
-                send_status(current_status)
-
-            case ChatCompletion(task_params=task_params, command_id=command_id) if (
-                isinstance(current_status, (RunnerReady, RunnerRunning))
-            ):
-                assert batch_engine is not None
-
-                # In distributed mode, only rank 0 should queue requests
-                # Other ranks should skip - they'll participate in sync_and_insert_pending()
-                is_distributed_mode = group is not None and group.size() > 1
-                if is_distributed_mode and shard_metadata.device_rank != 0:
-                    logger.debug(
-                        f"Rank {shard_metadata.device_rank} skipping ChatCompletionTask (only rank 0 queues)"
-                    )
-                    return True
-
-                if task_params.messages and task_params.messages[0].content is not None:
-                    _check_for_debug_prompts(task_params.messages[0].content)
-
-                # Queue the request - actual insertion happens in sync_and_insert_pending()
-                batch_engine.queue_request(
-                    command_id=command_id, task_id=task.task_id, task_params=task_params
-                )
-
-                # Status will be updated after actual insertion in the main loop
-                # For now, set to RunnerRunning to indicate we're processing
-                current_status = RunnerRunning(
-                    active_requests=batch_engine.active_count
-                    + batch_engine.pending_insert_count
-                )
-                send_status(current_status)
-
-            case ImageGeneration(
-                task_params=task_params, command_id=command_id
-            ) if isinstance(current_status, RunnerReady):
-                assert isinstance(model, DistributedImageModel)
-                logger.info(f"received image generation request: {str(task)[:500]}")
-                current_status = RunnerRunning()
-                logger.info("runner running")
-                send_status(current_status)
-
-                try:
-                    # Generate images using the image generation backend
-                    # Track image_index for final images only
-                    image_index = 0
-                    for response in generate_image(model=model, task=task_params):
-                        if (
-                            shard_metadata.device_rank
-                            == shard_metadata.world_size - 1
-                        ):
-                            match response:
-                                case PartialImageResponse():
-                                    logger.info(
-                                        f"sending partial ImageChunk {response.partial_index}/{response.total_partials}"
-                                    )
-                                    _process_image_response(
-                                        response,
-                                        command_id,
-                                        shard_metadata,
-                                        event_sender,
-                                        image_index,
-                                    )
-                                case ImageGenerationResponse():
-                                    logger.info("sending final ImageChunk")
-                                    _process_image_response(
-                                        response,
-                                        command_id,
-                                        shard_metadata,
-                                        event_sender,
-                                        image_index,
-                                    )
-                                    image_index += 1
-                except Exception as e:
-                    if shard_metadata.device_rank == shard_metadata.world_size - 1:
-                        event_sender.send(
-                            ChunkGenerated(
-                                command_id=command_id,
-                                chunk=ImageChunk(
-                                    idx=0,
-                                    model=shard_metadata.model_card.model_id,
-                                    data="",
-                                    chunk_index=0,
-                                    total_chunks=1,
-                                    image_index=0,
-                                    finish_reason="error",
-                                    error_message=str(e),
-                                ),
-                            )
+                        raise ValueError(
+                            f"Unknown model task(s): {shard_metadata.model_card.tasks}"
                         )
-                    raise
 
-                current_status = RunnerReady()
-                logger.info("runner ready")
-                event_sender.send(
-                    TaskStatusUpdated(
-                        task_id=task.task_id, task_status=TaskStatus.Complete
-                    )
-                )
-                send_status(current_status)
+                    current_status = RunnerLoaded()
+                    logger.info("runner loaded")
+                case StartWarmup() if isinstance(current_status, RunnerLoaded):
+                    assert model
 
-            case ImageEdits(task_params=task_params, command_id=command_id) if (
-                isinstance(current_status, RunnerReady)
-            ):
-                assert isinstance(model, DistributedImageModel)
-                logger.info(f"received image edits request: {str(task)[:500]}")
-                current_status = RunnerRunning()
-                logger.info("runner running")
-                send_status(current_status)
-
-                try:
-                    image_index = 0
-                    for response in generate_image(model=model, task=task_params):
-                        if (
-                            shard_metadata.device_rank
-                            == shard_metadata.world_size - 1
-                        ):
-                            match response:
-                                case PartialImageResponse():
-                                    logger.info(
-                                        f"sending partial ImageChunk {response.partial_index}/{response.total_partials}"
-                                    )
-                                    _process_image_response(
-                                        response,
-                                        command_id,
-                                        shard_metadata,
-                                        event_sender,
-                                        image_index,
-                                    )
-                                case ImageGenerationResponse():
-                                    logger.info("sending final ImageChunk")
-                                    _process_image_response(
-                                        response,
-                                        command_id,
-                                        shard_metadata,
-                                        event_sender,
-                                        image_index,
-                                    )
-                                    image_index += 1
-                except Exception as e:
-                    if shard_metadata.device_rank == shard_metadata.world_size - 1:
-                        event_sender.send(
-                            ChunkGenerated(
-                                command_id=command_id,
-                                chunk=ImageChunk(
-                                    idx=0,
-                                    model=shard_metadata.model_card.model_id,
-                                    data="",
-                                    chunk_index=0,
-                                    total_chunks=1,
-                                    image_index=0,
-                                    finish_reason="error",
-                                    error_message=str(e),
-                                ),
-                            )
+                    current_status = RunnerWarmingUp()
+                    logger.info("runner warming up")
+                    event_sender.send(
+                        RunnerStatusUpdated(
+                            runner_id=runner_id, runner_status=current_status
                         )
-                    raise
-
-                current_status = RunnerReady()
-                logger.info("runner ready")
-                event_sender.send(
-                    TaskStatusUpdated(
-                        task_id=task.task_id, task_status=TaskStatus.Complete
                     )
-                )
-                send_status(current_status)
 
-            case Shutdown():
-                current_status = RunnerShuttingDown()
-                logger.info("runner shutting down")
-                send_status(current_status)
-                event_sender.send(
-                    TaskStatusUpdated(
-                        task_id=task.task_id, task_status=TaskStatus.Complete
-                    )
-                )
-                current_status = RunnerShutdown()
-                send_status(current_status)
-                return False
+                    logger.info(f"warming up inference for instance: {instance}")
+                    if ModelTask.TextGeneration in shard_metadata.model_card.tasks:
+                        assert not isinstance(model, DistributedImageModel)
+                        assert tokenizer
 
-            case _:
-                raise ValueError(
-                    f"Received {task.__class__.__name__} outside of state machine in {current_status=}"
-                )
+                        toks = warmup_inference(
+                            model=model,
+                            tokenizer=tokenizer,
+                            # kv_prefix_cache=kv_prefix_cache,  # supply for warmup-time prefix caching
+                        )
+                        logger.info(f"warmed up by generating {toks} tokens")
+                        logger.info(
+                            f"runner initialized in {time.time() - setup_start_time} seconds"
+                        )
+                    elif (
+                        ModelTask.TextToImage in shard_metadata.model_card.tasks
+                        or ModelTask.ImageToImage in shard_metadata.model_card.tasks
+                    ):
+                        assert isinstance(model, DistributedImageModel)
+                        image = warmup_image_generator(model=model)
+                        if image is not None:
+                            logger.info(f"warmed up by generating {image.size} image")
+                        else:
+                            logger.info("warmup completed (non-primary node)")
 
-        return True
-
-    with task_receiver as tasks:
-        running = True
-        is_rank_0 = shard_metadata.device_rank == 0
-
-        while running:
-            # Use batch_engine.is_distributed since it's set correctly after group initialization
-            # (the group variable is None at loop start, but set by ConnectToGroup task)
-            if batch_engine is not None and batch_engine.is_distributed:
-                assert group is not None
-                assert batch_engine is not None
-
-                # Distributed mode: tasks wake up all ranks, then we sync and generate
-
-                # Check deferred shutdown FIRST - all ranks must check and process together
-                # This must run before any collective operations to prevent deadlock
-                if (
-                    pending_shutdown is not None
-                    and not batch_engine.has_active_requests
-                    and not batch_engine.has_pending_inserts
+                    current_status = RunnerReady()
+                    logger.info("runner ready")
+                case ChatCompletion(task_params=task_params, command_id=command_id) if (
+                    isinstance(current_status, RunnerReady)
                 ):
-                    handle_task(pending_shutdown, is_deferred=True)
-                    running = False
-                    continue
-
-                # When idle, block waiting for task (exo sends tasks to all ranks)
-                # When active, poll non-blocking to batch incoming requests
-                if (
-                    not batch_engine.has_active_requests
-                    and not batch_engine.has_pending_inserts
-                ):
-                    # IDLE: Block until task arrives (all ranks receive the same task)
-                    task = tasks.receive()
-                    task_result = handle_task(task)
-                    if not task_result:
-                        running = False
-                        continue
-                else:
-                    # ACTIVE: Poll for new tasks without blocking
-                    while True:
-                        try:
-                            task = tasks.receive_nowait()
-                            task_result = handle_task(task)
-                            if not task_result:
-                                running = False
-                                break
-                        except WouldBlock:
-                            break
-                    if not running:
-                        continue
-
-                # Sync and insert pending requests (collective operation)
-                # Rank 0 broadcasts its pending to all ranks
-                inserted = batch_engine.sync_and_insert_pending()
-                if is_rank_0 and inserted:
-                    current_status = RunnerRunning(
-                        active_requests=batch_engine.active_count
+                    logger.info(f"received chat request: {task}")
+                    current_status = RunnerRunning()
+                    logger.info("runner running")
+                    event_sender.send(
+                        RunnerStatusUpdated(
+                            runner_id=runner_id, runner_status=current_status
+                        )
                     )
-                    send_status(current_status)
+                    assert model and not isinstance(model, DistributedImageModel)
+                    assert tokenizer
+                    assert task_params.messages[0].content is not None
 
-                # Run generation for time budget
-                if batch_engine.has_active_requests:
-                    time_budget = TimeBudget(budget=0.5, group=group)
-                    for _ in time_budget:
-                        if not batch_engine.has_active_requests:
-                            break
-                        for resp in batch_engine.step():
-                            # Send token IMMEDIATELY for smooth streaming (only rank 0)
-                            if is_rank_0:
-                                event_sender.send(
-                                    ChunkGenerated(
-                                        command_id=resp.command_id,
-                                        chunk=TokenChunk(
-                                            idx=resp.response.token,
-                                            model=shard_metadata.model_card.model_id,
-                                            text=resp.response.text,
-                                            token_id=resp.response.token,
-                                            finish_reason=resp.response.finish_reason,
-                                            stats=resp.response.stats,
-                                        ),
-                                    )
-                                )
-                                if resp.response.finish_reason is not None:
-                                    event_sender.send(
-                                        TaskStatusUpdated(
-                                            task_id=resp.task_id,
-                                            task_status=TaskStatus.Complete,
-                                        )
-                                    )
-
-                # Sync completions at budget boundary (always call - it's a collective operation)
-                batch_engine.sync_completions()
-
-                # Update status after budget
-                if is_rank_0:
-                    current_status = (
-                        RunnerRunning(active_requests=batch_engine.active_count)
-                        if batch_engine.has_active_requests
-                        else RunnerReady()
-                    )
-                    send_status(current_status)
-
-            elif batch_engine is not None:
-                # Non-distributed mode with batch engine: original logic with queue + insert
-                while True:
                     try:
-                        task = tasks.receive_nowait()
-                        running = handle_task(task)
-                        if not running:
-                            break
-                    except WouldBlock:
-                        break
+                        _check_for_debug_prompts(task_params.messages[0].content)
 
-                if not running:
-                    break
+                        # Build prompt once - used for both generation and thinking detection
+                        prompt = apply_chat_template(tokenizer, task_params)
 
-                # Insert any queued requests (non-distributed just inserts directly)
-                # Status was already sent in handle_task when queueing
-                if batch_engine.has_pending_inserts:
-                    batch_engine.sync_and_insert_pending()
+                        # Generate responses using the actual MLX generation
+                        mlx_generator = mlx_generate(
+                            model=model,
+                            tokenizer=tokenizer,
+                            task=task_params,
+                            prompt=prompt,
+                        )
 
-                if batch_engine.has_active_requests:
-                    for resp in batch_engine.step():
-                        if shard_metadata.device_rank == 0:
+                        # GPT-OSS specific parsing to match other model formats.
+                        if isinstance(model, GptOssModel):
+                            mlx_generator = parse_gpt_oss(mlx_generator)
+
+                        # For other thinking models (GLM, etc.), check if we need to
+                        # prepend the thinking tag that was consumed by the chat template
+                        if detect_thinking_prompt_suffix(prompt, tokenizer):
+                            mlx_generator = parse_thinking_models(
+                                mlx_generator, tokenizer
+                            )
+
+                        # TODO: Add tool call parser here
+
+                        for response in mlx_generator:
+                            match response:
+                                case GenerationResponse():
+                                    if device_rank == 0:
+                                        event_sender.send(
+                                            ChunkGenerated(
+                                                command_id=command_id,
+                                                chunk=TokenChunk(
+                                                    idx=response.token,
+                                                    model=shard_metadata.model_card.model_id,
+                                                    text=response.text,
+                                                    token_id=response.token,
+                                                    finish_reason=response.finish_reason,
+                                                    stats=response.stats,
+                                                ),
+                                            )
+                                        )
+
+                    # can we make this more explicit?
+                    except Exception as e:
+                        if device_rank == 0:
                             event_sender.send(
                                 ChunkGenerated(
-                                    command_id=resp.command_id,
+                                    command_id=command_id,
                                     chunk=TokenChunk(
-                                        idx=resp.response.token,
+                                        idx=0,
                                         model=shard_metadata.model_card.model_id,
-                                        text=resp.response.text,
-                                        token_id=resp.response.token,
-                                        finish_reason=resp.response.finish_reason,
-                                        stats=resp.response.stats,
+                                        text="",
+                                        token_id=0,
+                                        finish_reason="error",
+                                        error_message=str(e),
                                     ),
                                 )
                             )
-                        if resp.response.finish_reason is not None:
+                        raise
+
+                    current_status = RunnerReady()
+                    logger.info("runner ready")
+                case ImageGeneration(
+                    task_params=task_params, command_id=command_id
+                ) if isinstance(current_status, RunnerReady):
+                    assert isinstance(model, DistributedImageModel)
+                    logger.info(f"received image generation request: {str(task)[:500]}")
+                    current_status = RunnerRunning()
+                    logger.info("runner running")
+                    event_sender.send(
+                        RunnerStatusUpdated(
+                            runner_id=runner_id, runner_status=current_status
+                        )
+                    )
+
+                    try:
+                        # Generate images using the image generation backend
+                        # Track image_index for final images only
+                        image_index = 0
+                        for response in generate_image(model=model, task=task_params):
+                            if (
+                                shard_metadata.device_rank
+                                == shard_metadata.world_size - 1
+                            ):
+                                match response:
+                                    case PartialImageResponse():
+                                        logger.info(
+                                            f"sending partial ImageChunk {response.partial_index}/{response.total_partials}"
+                                        )
+                                        _process_image_response(
+                                            response,
+                                            command_id,
+                                            shard_metadata,
+                                            event_sender,
+                                            image_index,
+                                        )
+                                    case ImageGenerationResponse():
+                                        logger.info("sending final ImageChunk")
+                                        _process_image_response(
+                                            response,
+                                            command_id,
+                                            shard_metadata,
+                                            event_sender,
+                                            image_index,
+                                        )
+                                        image_index += 1
+                    except Exception as e:
+                        if shard_metadata.device_rank == shard_metadata.world_size - 1:
                             event_sender.send(
-                                TaskStatusUpdated(
-                                    task_id=resp.task_id,
-                                    task_status=TaskStatus.Complete,
+                                ChunkGenerated(
+                                    command_id=command_id,
+                                    chunk=ImageChunk(
+                                        idx=0,
+                                        model=shard_metadata.model_card.model_id,
+                                        data="",
+                                        chunk_index=0,
+                                        total_chunks=1,
+                                        image_index=0,
+                                        finish_reason="error",
+                                        error_message=str(e),
+                                    ),
                                 )
                             )
+                        raise
 
-                    if batch_engine.has_active_requests:
-                        current_status = RunnerRunning(
-                            active_requests=batch_engine.active_count
+                    current_status = RunnerReady()
+                    logger.info("runner ready")
+                case ImageEdits(task_params=task_params, command_id=command_id) if (
+                    isinstance(current_status, RunnerReady)
+                ):
+                    assert isinstance(model, DistributedImageModel)
+                    logger.info(f"received image edits request: {str(task)[:500]}")
+                    current_status = RunnerRunning()
+                    logger.info("runner running")
+                    event_sender.send(
+                        RunnerStatusUpdated(
+                            runner_id=runner_id, runner_status=current_status
                         )
-                    else:
-                        current_status = RunnerReady()
-                    send_status(current_status)
+                    )
 
-                    # Process deferred shutdown after all requests complete
-                    if (
-                        pending_shutdown is not None
-                        and not batch_engine.has_active_requests
-                        and not batch_engine.has_pending_inserts
-                    ):
-                        running = handle_task(pending_shutdown, is_deferred=True)
-                else:
-                    task = tasks.receive()
-                    running = handle_task(task)
-            else:
-                # No batch engine (image generation mode): simple synchronous handling
-                task = tasks.receive()
-                running = handle_task(task)
+                    try:
+                        image_index = 0
+                        for response in generate_image(model=model, task=task_params):
+                            if (
+                                shard_metadata.device_rank
+                                == shard_metadata.world_size - 1
+                            ):
+                                match response:
+                                    case PartialImageResponse():
+                                        logger.info(
+                                            f"sending partial ImageChunk {response.partial_index}/{response.total_partials}"
+                                        )
+                                        _process_image_response(
+                                            response,
+                                            command_id,
+                                            shard_metadata,
+                                            event_sender,
+                                            image_index,
+                                        )
+                                    case ImageGenerationResponse():
+                                        logger.info("sending final ImageChunk")
+                                        _process_image_response(
+                                            response,
+                                            command_id,
+                                            shard_metadata,
+                                            event_sender,
+                                            image_index,
+                                        )
+                                        image_index += 1
+                    except Exception as e:
+                        if shard_metadata.device_rank == shard_metadata.world_size - 1:
+                            event_sender.send(
+                                ChunkGenerated(
+                                    command_id=command_id,
+                                    chunk=ImageChunk(
+                                        idx=0,
+                                        model=shard_metadata.model_card.model_id,
+                                        data="",
+                                        chunk_index=0,
+                                        total_chunks=1,
+                                        image_index=0,
+                                        finish_reason="error",
+                                        error_message=str(e),
+                                    ),
+                                )
+                            )
+                        raise
 
-    # Cleanup
-    del model, tokenizer, group, batch_engine
-    mx.clear_cache()
-    gc.collect()
+                    current_status = RunnerReady()
+                    logger.info("runner ready")
+                case Shutdown():
+                    current_status = RunnerShuttingDown()
+                    logger.info("runner shutting down")
+                    event_sender.send(
+                        RunnerStatusUpdated(
+                            runner_id=runner_id, runner_status=current_status
+                        )
+                    )
+                    current_status = RunnerShutdown()
+                case _:
+                    raise ValueError(
+                        f"Received {task.__class__.__name__} outside of state machine in {current_status=}"
+                    )
+            event_sender.send(
+                TaskStatusUpdated(task_id=task.task_id, task_status=TaskStatus.Complete)
+            )
+            event_sender.send(
+                RunnerStatusUpdated(runner_id=runner_id, runner_status=current_status)
+            )
+            if isinstance(current_status, RunnerShutdown):
+                del model, tokenizer, group
+                mx.clear_cache()
+                import gc
+
+                gc.collect()
+                break
+
+
+@cache
+def get_gpt_oss_encoding():
+    encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
+    return encoding
+
+
+def parse_gpt_oss(
+    responses: Generator[GenerationResponse],
+) -> Generator[GenerationResponse]:
+    encoding = get_gpt_oss_encoding()
+    stream = StreamableParser(encoding, role=Role.ASSISTANT)
+    thinking = False
+
+    for response in responses:
+        stream.process(response.token)
+
+        delta = stream.last_content_delta
+        ch = stream.current_channel
+
+        if ch == "analysis" and not thinking:
+            thinking = True
+            yield response.model_copy(update={"text": "<think>"})
+
+        if ch != "analysis" and thinking:
+            thinking = False
+            yield response.model_copy(update={"text": "</think>"})
+
+        if delta:
+            yield response.model_copy(update={"text": delta})
+
+        if response.finish_reason is not None:
+            if thinking:
+                yield response.model_copy(update={"text": "</think>"})
+            yield response
+            break
+
+
+def parse_thinking_models(
+    responses: Generator[GenerationResponse],
+    tokenizer: TokenizerWrapper,
+) -> Generator[GenerationResponse]:
+    """
+    For models that inject thinking tags in the prompt (like GLM-4.7),
+    prepend the thinking tag to the output stream so the frontend
+    can properly parse thinking content.
+    """
+    first = True
+    for response in responses:
+        if first:
+            first = False
+            yield response.model_copy(
+                update={
+                    "text": tokenizer.think_start,
+                    "token": tokenizer.think_start_id,  # type: ignore
+                }
+            )
+        yield response
 
 
 def _send_image_chunk(

src/exo/worker/runner/runner_supervisor.py

@@ -105,7 +105,7 @@ class RunnerSupervisor:
             return
 
         # This is overkill but it's not technically bad, just unnecessary.
-        logger.warning("Runner process didn't shutdown successfully, terminating")
+        logger.warning("Runner process didn't shutdown succesfully, terminating")
         self.runner_process.terminate()
         await to_thread.run_sync(self.runner_process.join, 5)
         if not self.runner_process.is_alive():
@@ -128,11 +128,9 @@ class RunnerSupervisor:
 
     async def start_task(self, task: Task):
         if task.task_id in self.completed:
-            logger.info(f"Skipping task {task.task_id} - already completed")
-            return
-        if task.task_id in self.pending:
-            logger.info(f"Skipping task {task.task_id} - already pending")
-            return
+            logger.info(
+                f"Skipping invalid task {task} as it has already been completed"
+            )
         logger.info(f"Starting task {task}")
         event = anyio.Event()
         self.pending[task.task_id] = event
@@ -151,17 +149,13 @@ class RunnerSupervisor:
                     if isinstance(event, RunnerStatusUpdated):
                         self.status = event.runner_status
                     if isinstance(event, TaskAcknowledged):
-                        # Just set the event to unblock start_task, but keep in pending
-                        # to prevent duplicate forwarding until completion
-                        if event.task_id in self.pending:
-                            self.pending[event.task_id].set()
+                        self.pending.pop(event.task_id).set()
                         continue
-                    if isinstance(event, TaskStatusUpdated) and event.task_status in (
-                        TaskStatus.Complete,
-                        TaskStatus.TimedOut,
-                        TaskStatus.Failed,
+                    if (
+                        isinstance(event, TaskStatusUpdated)
+                        and event.task_status == TaskStatus.Complete
                     ):
-                        # If a task has just finished, we should be working on it.
+                        # If a task has just been completed, we should be working on it.
                         assert isinstance(
                             self.status,
                             (
@@ -172,8 +166,6 @@ class RunnerSupervisor:
                                 RunnerShuttingDown,
                             ),
                         )
-                        # Now safe to remove from pending and add to completed
-                        self.pending.pop(event.task_id, None)
                         self.completed.add(event.task_id)
                     await self._event_sender.send(event)
             except (ClosedResourceError, BrokenResourceError) as e:

src/exo/worker/tests/unittests/conftest.py

@@ -20,7 +20,6 @@ class FakeRunnerSupervisor:
     bound_instance: BoundInstance
     status: RunnerStatus
     completed: set[TaskId] = field(default_factory=set)
-    pending: dict[TaskId, object] = field(default_factory=dict)
 
 
 class OtherTask(BaseTask):

src/exo/worker/tests/unittests/test_runner/test_continuous_batching.py

@@ -1,330 +0,0 @@
-"""
-Tests for continuous batching behavior in the runner.
-
-These tests verify that:
-1. Single requests work through the batch path
-2. Multiple concurrent requests batch together
-3. Tokens are routed to the correct requests
-4. Requests complete at different times appropriately
-"""
-
-# pyright: reportAny=false
-# pyright: reportUnknownArgumentType=false
-# pyright: reportUnknownMemberType=false
-# pyright: reportAttributeAccessIssue=false
-# pyright: reportInvalidTypeVarUse=false
-
-from typing import Any
-from unittest.mock import MagicMock
-
-import pytest
-
-import exo.worker.runner.runner as mlx_runner
-from exo.shared.types.api import ChatCompletionMessage
-from exo.shared.types.common import CommandId, NodeId
-from exo.shared.types.events import (
-    Event,
-    RunnerStatusUpdated,
-    TaskStatusUpdated,
-)
-from exo.shared.types.tasks import (
-    ChatCompletion,
-    ChatCompletionTaskParams,
-    ConnectToGroup,
-    LoadModel,
-    Shutdown,
-    StartWarmup,
-    Task,
-    TaskId,
-    TaskStatus,
-)
-from exo.shared.types.worker.runner_response import GenerationResponse
-from exo.shared.types.worker.runners import RunnerRunning
-from exo.utils.channels import mp_channel
-from exo.worker.engines.mlx.generator.batch_engine import (
-    BatchedGenerationResponse,
-)
-from exo.worker.tests.constants import (
-    INSTANCE_1_ID,
-    MODEL_A_ID,
-    NODE_A,
-    RUNNER_1_ID,
-)
-from exo.worker.tests.unittests.conftest import get_bound_mlx_ring_instance
-
-
-class FakeBatchEngineWithTokens:
-    """
-    Fake batch engine that generates a specified number of tokens per request.
-
-    This simulates realistic batch generation behavior where:
-    - Requests are queued on insert
-    - Each step() call generates one token for all active requests
-    - Requests complete when they've generated all their tokens
-    """
-
-    def __init__(self, *_args: Any, **_kwargs: Any):
-        self._active_requests: dict[int, tuple[CommandId, TaskId, int, int]] = {}
-        self._pending_inserts: list[
-            tuple[CommandId, TaskId, ChatCompletionTaskParams]
-        ] = []
-        self._uid_counter = 0
-        self._tokens_per_request = 3  # Default: generate 3 tokens before completing
-        self.rank = 0  # Fake rank for testing
-
-    def queue_request(
-        self,
-        command_id: CommandId,
-        task_id: TaskId,
-        task_params: ChatCompletionTaskParams,
-    ) -> None:
-        """Queue a request for insertion."""
-        self._pending_inserts.append((command_id, task_id, task_params))
-
-    def sync_and_insert_pending(self) -> list[int]:
-        """Insert all pending requests."""
-        uids: list[int] = []
-        for command_id, task_id, task_params in self._pending_inserts:
-            uid = self._do_insert(command_id, task_id, task_params)
-            uids.append(uid)
-        self._pending_inserts.clear()
-        return uids
-
-    @property
-    def has_pending_inserts(self) -> bool:
-        return len(self._pending_inserts) > 0
-
-    def _do_insert(
-        self,
-        command_id: CommandId,
-        task_id: TaskId,
-        task_params: ChatCompletionTaskParams | None,
-    ) -> int:
-        uid = self._uid_counter
-        self._uid_counter += 1
-        # Track: (command_id, task_id, tokens_generated, max_tokens)
-        max_tokens = task_params.max_tokens if task_params else self._tokens_per_request
-        self._active_requests[uid] = (command_id, task_id, 0, max_tokens or 3)
-        return uid
-
-    def step(self) -> list[BatchedGenerationResponse]:
-        results: list[BatchedGenerationResponse] = []
-        uids_to_remove: list[int] = []
-
-        for uid, (command_id, task_id, tokens_gen, max_tokens) in list(
-            self._active_requests.items()
-        ):
-            tokens_gen += 1
-            finish_reason = "stop" if tokens_gen >= max_tokens else None
-            text = f"token{tokens_gen}"
-
-            if finish_reason:
-                uids_to_remove.append(uid)
-            else:
-                self._active_requests[uid] = (
-                    command_id,
-                    task_id,
-                    tokens_gen,
-                    max_tokens,
-                )
-
-            results.append(
-                BatchedGenerationResponse(
-                    command_id=command_id,
-                    task_id=task_id,
-                    response=GenerationResponse(
-                        token=tokens_gen,
-                        text=text,
-                        finish_reason=finish_reason,
-                    ),
-                )
-            )
-
-        for uid in uids_to_remove:
-            del self._active_requests[uid]
-
-        return results
-
-    @property
-    def has_active_requests(self) -> bool:
-        return len(self._active_requests) > 0
-
-    @property
-    def active_count(self) -> int:
-        return len(self._active_requests)
-
-    @property
-    def pending_insert_count(self) -> int:
-        return len(self._pending_inserts)
-
-    @property
-    def is_distributed(self) -> bool:
-        return False  # Non-distributed mode for testing
-
-
-class FakeGroup:
-    """Fake MLX distributed group for testing."""
-
-    def size(self) -> int:
-        return 1  # Single node (non-distributed)
-
-
-def make_nothin[T, U, V](res: T):
-    def nothin(*_1: U, **_2: V) -> T:
-        return res
-
-    return nothin
-
-
-@pytest.fixture
-def patch_batch_engine(monkeypatch: pytest.MonkeyPatch):
-    """Patch MLX dependencies and use FakeBatchEngineWithTokens."""
-    monkeypatch.setattr(mlx_runner, "initialize_mlx", make_nothin(FakeGroup()))
-    monkeypatch.setattr(
-        mlx_runner, "load_mlx_items", make_nothin((MagicMock(), MagicMock()))
-    )
-    monkeypatch.setattr(mlx_runner, "warmup_inference", make_nothin(1))
-    monkeypatch.setattr(mlx_runner, "_check_for_debug_prompts", make_nothin(None))
-    monkeypatch.setattr(mlx_runner, "BatchGenerationEngine", FakeBatchEngineWithTokens)
-
-
-def _run_with_tasks(tasks: list[Task]) -> list[Event]:
-    """
-    Run tasks through the runner, adding shutdown at the end.
-
-    Tasks are sent in order, with shutdown sent last.
-    The batch engine processes between task handling.
-    """
-    bound_instance = get_bound_mlx_ring_instance(
-        instance_id=INSTANCE_1_ID,
-        model_id=MODEL_A_ID,
-        runner_id=RUNNER_1_ID,
-        node_id=NodeId(NODE_A),
-    )
-
-    task_sender, task_receiver = mp_channel[Task]()
-    event_sender, event_receiver = mp_channel[Event]()
-
-    shutdown_task = Shutdown(
-        task_id=TaskId("shutdown"),
-        instance_id=INSTANCE_1_ID,
-        runner_id=RUNNER_1_ID,
-    )
-
-    with task_sender, event_receiver:
-        # Send all tasks including shutdown
-        for t in tasks:
-            task_sender.send(t)
-        task_sender.send(shutdown_task)
-
-        # Disable cleanup methods to prevent issues
-        event_sender.close = lambda: None
-        event_sender.join = lambda: None
-        task_receiver.close = lambda: None
-        task_receiver.join = lambda: None
-
-        mlx_runner.main(bound_instance, event_sender, task_receiver)
-
-        return event_receiver.collect()
-
-
-INIT_TASK = ConnectToGroup(task_id=TaskId("init"), instance_id=INSTANCE_1_ID)
-LOAD_TASK = LoadModel(task_id=TaskId("load"), instance_id=INSTANCE_1_ID)
-WARMUP_TASK = StartWarmup(task_id=TaskId("warmup"), instance_id=INSTANCE_1_ID)
-
-
-def make_chat_task(
-    task_id: str, command_id: str, max_tokens: int = 3
-) -> ChatCompletion:
-    return ChatCompletion(
-        task_id=TaskId(task_id),
-        command_id=CommandId(command_id),
-        task_params=ChatCompletionTaskParams(
-            model=str(MODEL_A_ID),
-            messages=[ChatCompletionMessage(role="user", content="hello")],
-            stream=True,
-            max_tokens=max_tokens,
-        ),
-        instance_id=INSTANCE_1_ID,
-    )
-
-
-def test_single_request_generates_tokens(patch_batch_engine: None):
-    """
-    Verify a single request generates the expected tokens through the batch path.
-
-    Note: With the current non-blocking design, shutdown is processed before
-    batch steps run when all tasks are queued together. This test verifies
-    the runner status reflects active requests.
-    """
-    chat_task = make_chat_task("chat1", "cmd1", max_tokens=3)
-    events = _run_with_tasks([INIT_TASK, LOAD_TASK, WARMUP_TASK, chat_task])
-
-    # Find RunnerRunning status events - this shows the request was inserted
-    running_events = [
-        e
-        for e in events
-        if isinstance(e, RunnerStatusUpdated)
-        and isinstance(e.runner_status, RunnerRunning)
-    ]
-
-    assert len(running_events) >= 1, "Expected at least one RunnerRunning event"
-    assert running_events[0].runner_status.active_requests == 1
-
-
-def test_runner_status_reflects_active_requests(patch_batch_engine: None):
-    """Verify RunnerRunning status includes active_requests count."""
-    chat_task = make_chat_task("chat1", "cmd1", max_tokens=2)
-    events = _run_with_tasks([INIT_TASK, LOAD_TASK, WARMUP_TASK, chat_task])
-
-    # Find RunnerRunning status events
-    running_events = [
-        e
-        for e in events
-        if isinstance(e, RunnerStatusUpdated)
-        and isinstance(e.runner_status, RunnerRunning)
-    ]
-
-    assert len(running_events) > 0, "Expected at least one RunnerRunning event"
-    assert running_events[0].runner_status.active_requests == 1
-
-
-def test_chat_task_acknowledged(patch_batch_engine: None):
-    """Verify chat completion task is acknowledged with proper status updates."""
-    chat_task = make_chat_task("chat1", "cmd1", max_tokens=2)
-    events = _run_with_tasks([INIT_TASK, LOAD_TASK, WARMUP_TASK, chat_task])
-
-    # Find the chat task status events
-    chat_running = [
-        e
-        for e in events
-        if isinstance(e, TaskStatusUpdated)
-        and e.task_id == TaskId("chat1")
-        and e.task_status == TaskStatus.Running
-    ]
-
-    assert len(chat_running) == 1, "Expected exactly one chat task Running status"
-
-
-def test_multiple_requests_tracked(patch_batch_engine: None):
-    """Verify multiple concurrent requests are tracked in active_requests."""
-    chat1 = make_chat_task("chat1", "cmd1", max_tokens=2)
-    chat2 = make_chat_task("chat2", "cmd2", max_tokens=2)
-    events = _run_with_tasks([INIT_TASK, LOAD_TASK, WARMUP_TASK, chat1, chat2])
-
-    # Find RunnerRunning status events
-    running_events = [
-        e
-        for e in events
-        if isinstance(e, RunnerStatusUpdated)
-        and isinstance(e.runner_status, RunnerRunning)
-    ]
-
-    # Should have at least 2 RunnerRunning events (one per request inserted)
-    assert len(running_events) >= 2, (
-        f"Expected at least 2 RunnerRunning events, got {len(running_events)}"
-    )
-
-    # First should have 1 active request, second should have 2
-    assert running_events[0].runner_status.active_requests == 1
-    assert running_events[1].runner_status.active_requests == 2

src/exo/worker/tests/unittests/test_runner/test_event_ordering.py

@@ -1,17 +1,12 @@
 # Check tasks are complete before runner is ever ready.
-
-# pyright: reportAny=false
-
 from collections.abc import Iterable
-from typing import Any, Callable
-from unittest.mock import MagicMock
+from typing import Callable
 
 import pytest
 
 import exo.worker.runner.runner as mlx_runner
 from exo.shared.types.api import ChatCompletionMessage
 from exo.shared.types.chunks import TokenChunk
-from exo.shared.types.common import CommandId
 from exo.shared.types.events import (
     ChunkGenerated,
     Event,
@@ -27,7 +22,6 @@ from exo.shared.types.tasks import (
     Shutdown,
     StartWarmup,
     Task,
-    TaskId,
     TaskStatus,
 )
 from exo.shared.types.worker.runner_response import GenerationResponse
@@ -44,9 +38,6 @@ from exo.shared.types.worker.runners import (
     RunnerWarmingUp,
 )
 from exo.utils.channels import mp_channel
-from exo.worker.engines.mlx.generator.batch_engine import (
-    BatchedGenerationResponse,
-)
 
 from ...constants import (
     CHAT_COMPLETION_TASK_ID,
@@ -116,100 +107,22 @@ def assert_events_equal(test_events: Iterable[Event], true_events: Iterable[Even
         assert test_event == true_event, f"{test_event} != {true_event}"
 
 
-class FakeBatchEngine:
-    """
-    Fake batch engine for testing.
-
-    Queues requests on insert, returns one token per step.
-    The runner's non-blocking loop drains all tasks before running batch steps,
-    so this engine queues requests and has_active_requests returns True only
-    after at least one request has been inserted.
-    """
-
-    def __init__(self, *_args: Any, **_kwargs: Any):
-        self._active_requests: dict[int, tuple[CommandId, TaskId]] = {}
-        self._pending_inserts: list[
-            tuple[CommandId, TaskId, ChatCompletionTaskParams]
-        ] = []
-        self._uid_counter = 0
-        self.rank = 0  # Fake rank for testing
-
-    def queue_request(
-        self,
-        command_id: CommandId,
-        task_id: TaskId,
-        task_params: ChatCompletionTaskParams,
-    ) -> None:
-        """Queue a request for insertion."""
-        self._pending_inserts.append((command_id, task_id, task_params))
-
-    def sync_and_insert_pending(self) -> list[int]:
-        """Insert all pending requests."""
-        uids: list[int] = []
-        for command_id, task_id, _task_params in self._pending_inserts:
-            uid = self._uid_counter
-            self._uid_counter += 1
-            self._active_requests[uid] = (command_id, task_id)
-            uids.append(uid)
-        self._pending_inserts.clear()
-        return uids
-
-    @property
-    def has_pending_inserts(self) -> bool:
-        return len(self._pending_inserts) > 0
-
-    def step(self) -> list[BatchedGenerationResponse]:
-        results: list[BatchedGenerationResponse] = []
-        # Process all active requests - return one token and complete
-        for uid, (command_id, task_id) in list(self._active_requests.items()):
-            results.append(
-                BatchedGenerationResponse(
-                    command_id=command_id,
-                    task_id=task_id,
-                    response=GenerationResponse(
-                        token=0,
-                        text="hi",
-                        finish_reason="stop",
-                    ),
-                )
-            )
-            del self._active_requests[uid]
-        return results
-
-    @property
-    def has_active_requests(self) -> bool:
-        return len(self._active_requests) > 0
-
-    @property
-    def active_count(self) -> int:
-        return len(self._active_requests)
-
-    @property
-    def pending_insert_count(self) -> int:
-        return len(self._pending_inserts)
-
-    @property
-    def is_distributed(self) -> bool:
-        return False  # Non-distributed mode for testing
-
-
-class FakeGroup:
-    """Fake MLX distributed group for testing."""
-
-    def size(self) -> int:
-        return 1  # Single node (non-distributed)
-
-
 @pytest.fixture
 def patch_out_mlx(monkeypatch: pytest.MonkeyPatch):
-    # initialize_mlx returns a fake "group" (non-None for state machine)
-    monkeypatch.setattr(mlx_runner, "initialize_mlx", make_nothin(FakeGroup()))
-    monkeypatch.setattr(
-        mlx_runner, "load_mlx_items", make_nothin((MagicMock(), MagicMock()))
-    )
+    # initialize_mlx returns a "group" equal to 1
+    monkeypatch.setattr(mlx_runner, "initialize_mlx", make_nothin(1))
+    monkeypatch.setattr(mlx_runner, "load_mlx_items", make_nothin((1, 1)))
     monkeypatch.setattr(mlx_runner, "warmup_inference", make_nothin(1))
     monkeypatch.setattr(mlx_runner, "_check_for_debug_prompts", nothin)
-    monkeypatch.setattr(mlx_runner, "BatchGenerationEngine", FakeBatchEngine)
+    # Mock apply_chat_template since we're using a fake tokenizer (integer 1).
+    # Returns a prompt without thinking tag so detect_thinking_prompt_suffix returns None.
+    monkeypatch.setattr(mlx_runner, "apply_chat_template", make_nothin("test prompt"))
+    monkeypatch.setattr(mlx_runner, "detect_thinking_prompt_suffix", make_nothin(False))
+
+    def fake_generate(*_1: object, **_2: object):
+        yield GenerationResponse(token=0, text="hi", finish_reason="stop")
+
+    monkeypatch.setattr(mlx_runner, "mlx_generate", fake_generate)
 
 
 # Use a fake event_sender to remove test flakiness.
@@ -252,8 +165,7 @@ def _run(tasks: Iterable[Task]):
         return event_sender.events
 
 
-def test_chat_completion_generates_and_completes(patch_out_mlx: pytest.MonkeyPatch):
-    """Verify chat completion generates tokens, completes, and runner returns to Ready."""
+def test_events_processed_in_correct_order(patch_out_mlx: pytest.MonkeyPatch):
     events = _run([INIT_TASK, LOAD_TASK, WARMUP_TASK, CHAT_TASK, SHUTDOWN_TASK])
 
     expected_chunk = ChunkGenerated(
@@ -296,9 +208,7 @@ def test_chat_completion_generates_and_completes(patch_out_mlx: pytest.MonkeyPat
                 task_id=CHAT_COMPLETION_TASK_ID, task_status=TaskStatus.Running
             ),
             TaskAcknowledged(task_id=CHAT_COMPLETION_TASK_ID),
-            RunnerStatusUpdated(
-                runner_id=RUNNER_1_ID, runner_status=RunnerRunning(active_requests=1)
-            ),
+            RunnerStatusUpdated(runner_id=RUNNER_1_ID, runner_status=RunnerRunning()),
             expected_chunk,
             TaskStatusUpdated(
                 task_id=CHAT_COMPLETION_TASK_ID, task_status=TaskStatus.Complete
@@ -313,6 +223,7 @@ def test_chat_completion_generates_and_completes(patch_out_mlx: pytest.MonkeyPat
             TaskStatusUpdated(
                 task_id=SHUTDOWN_TASK_ID, task_status=TaskStatus.Complete
             ),
+            # SPECIAL EXCEPTION FOR RUNNER SHUTDOWN
             RunnerStatusUpdated(runner_id=RUNNER_1_ID, runner_status=RunnerShutdown()),
         ],
     )