Skip to main content
Normal createRouter behavior is selector-first: it selects a model, then executes it. Speculative routing starts a likely execution while the next route is being selected. This can reduce selector latency, but it makes state, cancellation, and reporting your responsibility.
This is an advanced host pattern. The Managed Router provides its own hosted implementation; createRouter does not speculate automatically.

Why use the phases?

prepareRoute() resolves candidates and prepares selector input. Once you have that result, your host can start a previously selected, still-compatible model. finalizeRoute() validates the selector’s next decision.
startModel, callSelector, serveOrRecover, and persistNextDecision are application functions. Router Core does not know how to start, cancel, persist, or bill them.

Eligibility is mandatory

Speculate only when the recovered model and reasoning level remain eligible for the current request. A changed tool set, image requirement, structured-output mode, stream mode, reasoning constraint, or routing rule can invalidate the incumbent. First turns and stale state should remain selector-first.

Separate the two decisions

The model serving this turn can differ from the decision selected for the next turn. Attribute tokens, latency, errors, and billing to the model that served. Persist the next decision separately. Do not report a speculative incumbent as if it were the selector’s result.

Failure policy

Define explicit behavior for every race:
  • If speculative startup fails, await the selected route.
  • If selection fails after startup, decide whether the incumbent may finish.
  • If the client disconnects, cancel both operations and close provider streams.
  • Persist routing state before emitting a terminal event when durable state is required.
If these rules are not worth owning, use selector-first createRouter instead.