speaker_helper.router module

Backend router: pick an engine + mode from measured quality↔speed evidence.

Module summary

The rest of speaker-helper measures a TTS operating point — real-time factor (RTF), anomaly rate, and a quality score (measured chrF, or an engine prior) — and can rank engines on the quality↔RTF plane (pareto_front()). What it historically did not do is act on that evidence: create_engine() just read settings.backend. This module closes that loop. Given an operating condition it returns a concrete, justified choice of engine, mode, and streaming knobs — never a vibe, always traceable to numbers.

Two conditions, two different objectives (this is the scientific core):

  • online real-time (delay-bounded / streaming). To sustain playback without underrun the engine must synthesise faster than real time: RTF < 1 is a hard feasibility boundary. We keep a margin for time-to-first-audio and jitter (default ceiling 0.8). Among the engines that keep up, we maximise quality. Mode is streaming with low-TTFA knobs (small first chunk, strict pipeline). If nothing keeps up, that is reported, not hidden.

  • offline (batch). There is no real-time constraint, and quality is the only objective: speed is not an objective at all. We pick the highest-quality engine outright, and the decision carries no RTF — mean_rtf is None and rtf_source is "not_considered", so a timing cannot be mistaken for part of the reasoning. The single exception is a patience budget the caller sets explicitly, which filters candidates and is named as the caller’s own constraint. Mode is offline. Where the owner has arbitrated a language himself (OFFLINE_RATIFIED_ENGINE — French since 2026-10-28), his choice takes the decision and the justification says which candidate it overrode: an arbitration is reported as an arbitration, never folded into the quality numbers.

For the online condition the choice is taken only from the Pareto front (the non-dominated set), so the router never returns a point some other engine beats on both axes while still keeping up. Offline is a pure quality argmax.

Where does the evidence come from? Strongest first:

  1. Measured reports — pass a list of EvalReport (from run_eval / run_multilang_eval / tune_profiles). Both axes are then measured on your host → the strongest evidence available.

  2. The built-in operating-point catalogue (default_operating_points()) — seeded from the per-language profiles (kokoro RTF measured in-process on this suite’s reference host) and the engine quality priors. RTF is known only where it was measured; other engines carry a quality prior and an unknown RTF, and are therefore excluded from online routing (we will not claim an engine keeps up if we never timed it).

Every decision states where each of its numbers came from, through quality_source and rtf_source. Those are facts about provenance, and they are all a reader gets — there is deliberately no derived “confidence” grade on top. A three-rung high/medium/low scale invented here would be a judgement wearing the costume of a measurement, and it had already started doing harm: a measured RTF was quietly promoting a bare prior to “medium” on the offline path. Read the provenance and draw your own conclusion.

Further characterisation of new engines is a study, not a toolbox concern — run it in the speak experiment repo and fold the resulting numbers back into the catalogue or pass them as reports.

Usage example

>>> from speaker_helper.router import route, RouteRequest
>>> d = route(RouteRequest(condition="online_realtime", language="fr"))
>>> d.engine
'kokoro'
>>> d.mode
'streaming'

Author

Warith HARCHAOUI — https://linkedin.com/in/warith-harchaoui

speaker_helper.router.OFFLINE_RATIFIED_AS_OF: str = '2026-10-28'

As-of date of the ratifications above — a decision carries its date, same rule as PUBLIC_ELO_AS_OF and LANDSCAPE.md’s licence table.

class speaker_helper.router.OperatingPoint(engine, quality, mean_rtf, quality_source='prior', rtf_source='unknown', backend='kokoro', language=None)[source]

Bases: object

One engine’s position on the quality↔speed plane, with provenance.

Parameters:
  • engine (str) – Engine/model id (e.g. "kokoro").

  • quality (float) – Quality score in [0, 1] to maximise (measured chrF or a prior).

  • mean_rtf (float or None) – Mean real-time factor to minimise; None when never measured (the engine then cannot be routed for the online condition).

  • quality_source (str) – "measured_chrf" or "prior" — how quality was obtained.

  • rtf_source (str) – "measured", "estimate", or "unknown" — how mean_rtf was obtained.

  • backend (str) – The backend that serves this engine (default "kokoro").

  • language (str or None) – Language the measurement pertains to, when language-specific.

backend: str = 'kokoro'
engine: str
language: str | None = None
mean_rtf: float | None
quality: float
quality_source: str = 'prior'
rtf_source: str = 'unknown'
class speaker_helper.router.RouteDecision(condition, engine, backend, mode, first_chunk_sentences, stream_concurrency, quality, mean_rtf, quality_source, rtf_source, justification, candidates_considered, pareto_size, owner_ratified=False)[source]

Bases: object

A concrete, justified operating point the caller can act on.

Parameters:
  • condition (str) – The condition this decision answers.

  • engine (str) – The chosen engine and the backend that serves it.

  • backend (str) – The chosen engine and the backend that serves it.

  • mode (str) – "streaming" (online) or "offline".

  • first_chunk_sentences (int) – Streaming producer/consumer knobs implied by the condition (only meaningful when mode == "streaming").

  • stream_concurrency (int) – Streaming producer/consumer knobs implied by the condition (only meaningful when mode == "streaming").

  • quality (float) – The chosen point’s quality score.

  • mean_rtf (float or None) – The chosen point’s mean RTF. Always ``None`` for an offline decision: RTF is not an objective there, so it is not reported.

  • quality_source (str) – Provenance of the two axes (see OperatingPoint). Offline decisions carry rtf_source="not_considered".

  • rtf_source (str) – Provenance of the two axes (see OperatingPoint). Offline decisions carry rtf_source="not_considered".

  • justification (str) – A human-readable, number-citing explanation of why this point won.

  • candidates_considered (int) – How many candidates were weighed and how many survived to the Pareto front — for auditability.

  • pareto_size (int) – How many candidates were weighed and how many survived to the Pareto front — for auditability.

  • owner_ratified (bool) – True when this engine was taken from OFFLINE_RATIFIED_ENGINE rather than won on the quality axis. The justification then names the candidate it overrode and that candidate’s score.

apply(settings=None)[source]

Return settings (or fresh defaults) reconfigured for this decision.

Parameters:

settings (Settings or None) – Base configuration to derive from; None uses defaults.

Returns:

A copy carrying the chosen backend, engine, mode, and (for streaming) the first-chunk granularity. stream_concurrency is a Speaker argument, not a Settings field, so read it off this decision separately (see from_route()).

Return type:

Settings

backend: str
candidates_considered: int
condition: str
engine: str
first_chunk_sentences: int
justification: str
mean_rtf: float | None
mode: str
owner_ratified: bool = False
pareto_size: int
quality: float
quality_source: str
rtf_source: str
stream_concurrency: int
to_dict()[source]

Return a JSON-serialisable dict of the decision (for API / CLI).

Return type:

dict

class speaker_helper.router.RouteRequest(condition, language='fr', rtf_ceiling=0.8, rtf_budget=None, quality_floor=None, require_measured_rtf=True, respect_ratification=True)[source]

Bases: object

What the caller needs; the router turns it into a justified choice.

Parameters:
  • condition (str) – "online_realtime" (delay-bounded streaming) or "offline" (throughput / quality). See CONDITIONS.

  • language (str) – ISO-639-1 target language (drives the default catalogue and profile).

  • rtf_ceiling (float) – Online only: the hard mean_rtf bound an engine must beat to be feasible. Defaults to DEFAULT_RTF_CEILING (0.8).

  • rtf_budget (float or None) – Offline only: an optional patience cap the caller may impose (None, the default, = no cap — quality is all that matters). This is the one place RTF can touch an offline route, and it is opt-in: the router never introduces a speed criterion of its own there.

  • quality_floor (float or None) – Reject any candidate below this quality, in both conditions (None = no floor).

  • require_measured_rtf (bool) – Online only: refuse engines whose RTF was never measured (default True — do not claim an untimed engine keeps up).

  • respect_ratification (bool) – Offline only: honour OFFLINE_RATIFIED_ENGINE for this language (default True). Set False to see the unarbitrated quality argmax — what a study comparing engines wants, and what makes the owner’s override visible as an override.

condition: str
language: str = 'fr'
quality_floor: float | None = None
require_measured_rtf: bool = True
respect_ratification: bool = True
rtf_budget: float | None = None
rtf_ceiling: float = 0.8
speaker_helper.router.default_operating_points(language='fr', condition='offline')[source]

Build the fallback candidate set for language under condition.

The per-language profile supplies kokoro’s measured RTF (in-process tuning) and MEASURED_RTF supplies the other engines’ (the speak study’s streaming bench) — performance is one axis for both conditions. Quality, by contrast, is condition-specific (see _quality_for()): the owner-ratified priors offline, the public arena Elo online.

Parameters:
  • language (str) – Language whose profile seeds the measured kokoro point.

  • condition (str) – ONLINE_REALTIME or OFFLINE (default — the historical behaviour of this function).

Returns:

One candidate per known engine, provenance flagged on both axes.

Return type:

list of OperatingPoint

speaker_helper.router.route(request, *, points=None, reports=None)[source]

Choose a justified engine + mode for request from the evidence.

Parameters:
  • request (RouteRequest) – The condition and its constraints.

  • points (sequence of OperatingPoint or None) – Explicit candidate operating points. When None and reports is also None, the built-in catalogue for request.language is used.

  • reports (sequence of EvalReport or None) – Measured reports to derive candidates from (the strongest evidence). Takes precedence over points when both are given.

Returns:

The chosen operating point, mode, streaming knobs, and a number-citing justification.

Return type:

RouteDecision

Raises:

ValueError – If request.condition is unknown, or no candidate satisfies the condition’s constraints (e.g. no engine keeps up online).

Examples

>>> route(RouteRequest(condition="offline", language="fr")).mode
'offline'
speaker_helper.router.route_settings(condition, *, language='fr', settings=None, **request_kwargs)[source]

Convenience: route for condition and return applied settings + decision.

Parameters:
  • condition (str) – "online_realtime" or "offline".

  • language (str) – Target language.

  • settings (Settings or None) – Base settings to reconfigure; None uses defaults.

  • **request_kwargs – Extra RouteRequest fields (rtf_ceiling, rtf_budget, quality_floor, require_measured_rtf).

Returns:

Settings reconfigured for the decision, and the decision itself (its stream_concurrency still needs forwarding to Speaker).

Return type:

tuple of (Settings, RouteDecision)