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 < 1is a hard feasibility boundary. We keep a margin for time-to-first-audio and jitter (default ceiling0.8). Among the engines that keep up, we maximise quality. Mode isstreamingwith 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_rtfisNoneandrtf_sourceis"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 isoffline. 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:
Measured reports — pass a list of
EvalReport(fromrun_eval/run_multilang_eval/tune_profiles). Both axes are then measured on your host → the strongest evidence available.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'
- 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:
objectOne 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;
Nonewhen never measured (the engine then cannot be routed for the online condition).quality_source (str) –
"measured_chrf"or"prior"— howqualitywas obtained.rtf_source (str) –
"measured","estimate", or"unknown"— howmean_rtfwas obtained.backend (str) – The backend that serves this engine (default
"kokoro").language (str or None) – Language the measurement pertains to, when language-specific.
- 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:
objectA 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 carryrtf_source="not_considered".rtf_source (str) – Provenance of the two axes (see
OperatingPoint). Offline decisions carryrtf_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) –
Truewhen this engine was taken fromOFFLINE_RATIFIED_ENGINErather than won on the quality axis. Thejustificationthen 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;
Noneuses defaults.- Returns:
A copy carrying the chosen backend, engine, mode, and (for streaming) the first-chunk granularity.
stream_concurrencyis aSpeakerargument, not aSettingsfield, so read it off this decision separately (seefrom_route()).- Return type:
- 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:
objectWhat the caller needs; the router turns it into a justified choice.
- Parameters:
condition (str) –
"online_realtime"(delay-bounded streaming) or"offline"(throughput / quality). SeeCONDITIONS.language (str) – ISO-639-1 target language (drives the default catalogue and profile).
rtf_ceiling (float) – Online only: the hard
mean_rtfbound an engine must beat to be feasible. Defaults toDEFAULT_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_ENGINEfor this language (defaultTrue). SetFalseto see the unarbitrated quality argmax — what a study comparing engines wants, and what makes the owner’s override visible as an override.
- speaker_helper.router.default_operating_points(language='fr', condition='offline')[source]
Build the fallback candidate set for
languageundercondition.The per-language profile supplies kokoro’s measured RTF (in-process tuning) and
MEASURED_RTFsupplies 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:
- Returns:
One candidate per known engine, provenance flagged on both axes.
- Return type:
- speaker_helper.router.route(request, *, points=None, reports=None)[source]
Choose a justified engine + mode for
requestfrom the evidence.- Parameters:
request (RouteRequest) – The condition and its constraints.
points (sequence of OperatingPoint or None) – Explicit candidate operating points. When
Noneandreportsis alsoNone, the built-in catalogue forrequest.languageis used.reports (sequence of EvalReport or None) – Measured reports to derive candidates from (the strongest evidence). Takes precedence over
pointswhen both are given.
- Returns:
The chosen operating point, mode, streaming knobs, and a number-citing justification.
- Return type:
- Raises:
ValueError – If
request.conditionis 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
conditionand return applied settings + decision.- Parameters:
condition (str) –
"online_realtime"or"offline".language (str) – Target language.
settings (Settings or None) – Base settings to reconfigure;
Noneuses defaults.**request_kwargs – Extra
RouteRequestfields (rtf_ceiling,rtf_budget,quality_floor,require_measured_rtf).
- Returns:
Settings reconfigured for the decision, and the decision itself (its
stream_concurrencystill needs forwarding toSpeaker).- Return type:
tuple of (Settings, RouteDecision)