Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(voice): speech spend is measured where it is spent

rubenluetke10-beepa55c6e9f68d0
diff --git a/jarvis/costs/model.py b/jarvis/costs/model.py
index 11e9a40e64..b94c55d829 100644
--- a/jarvis/costs/model.py
+++ b/jarvis/costs/model.py
@@ -137,7 +137,11 @@ class CostEntry:
@property
def is_gap(self) -> bool:
"""True when tokens were spent at a price nobody knows."""
- return self.price_source == "unknown" and self.tokens_total > 0
+ # No token guard: both pricing functions answer ``recorded`` when
+ # nothing was consumed, so ``unknown`` already means something WAS.
+ # Requiring tokens hid every speech gap, which is billed in characters
+ # and audio seconds and carries no tokens by design.
+ return self.price_source == "unknown"
def to_dict(self) -> dict[str, Any]:
return {
diff --git a/jarvis/costs/speech_rates.py b/jarvis/costs/speech_rates.py
new file mode 100644
index 0000000000..9184644137
--- /dev/null
+++ b/jarvis/costs/speech_rates.py
@@ -0,0 +1,282 @@
+"""Published rates for the two services that do not bill by token.
+
+:mod:`jarvis.costs.model` prices everything that bills per token. Speech does
+not: a transcription is billed per minute of audio, a synthesis per character
+of text, and one family (Google) bills speech per token but converts audio and
+text into tokens with published ratios of its own. Three units, one answer, so
+this module mirrors ``price_entry`` exactly — same four-way honesty, same
+"``unknown`` is a GAP, never a quiet zero".
+
+**Every number below carries the page it came from and the date it was read.**
+A rate nobody can trace is worse than no rate: it looks like accounting and is
+actually a guess, and the person it misleads is the one paying the bill. Where
+a vendor publishes no per-character or per-minute price at all — Cartesia sells
+credits, xAI publishes nothing for voice, an OpenRouter speech model is priced
+by whichever upstream serves it — the answer is ``unknown``. That row shows up
+in the report as a gap somebody can go close, which is the truth, instead of a
+zero that quietly says the audio was free.
+
+Rates are pay-as-you-go / on-demand list prices, the only tier a downloader
+with their own key can be assumed to be on. A cheaper committed tier makes the
+number an over-estimate, which is the safe direction for a spend report.
+
+The providers covered are the ones that exist in the code — every ``name`` in
+``jarvis/plugins/stt/`` and ``jarvis/plugins/tts/`` — not a remembered list.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from jarvis.costs.model import LOCAL_PROVIDERS, PriceSource
+
+STAGE_STT = "stt"
+STAGE_TTS = "tts"
+
+#: Speech engines that run on the user's own hardware. 0.00 is the truth here,
+#: not a missing rate. ``LOCAL_PROVIDERS`` in :mod:`jarvis.costs.model` covers
+#: the brain-side ids; these are the speech plugin ids it does not know, taken
+#: from the ``name`` of each local plugin class.
+LOCAL_SPEECH_PROVIDERS: frozenset[str] = frozenset(
+ {
+ "faster-whisper", # jarvis/plugins/stt/fwhisper.py
+ "nemotron-local", # jarvis/plugins/stt/nemotron_local.py
+ "piper-local", # jarvis/plugins/tts/piper_local.py
+ }
+)
+
+# ---------------------------------------------------------------------------
+# Rate shapes
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class MinuteRate:
+ """Billed per minute of audio submitted — the normal STT contract."""
+
+ usd_per_minute: float
+ source: str
+
+ def usd(self, chars: int, audio_ms: int) -> float:
+ return audio_ms / 60_000.0 * self.usd_per_minute
+
+
+@dataclass(frozen=True, slots=True)
+class CharRate:
+ """Billed per character of input text — the normal TTS contract."""
+
+ usd_per_million_chars: float
+ source: str
+
+ def usd(self, chars: int, audio_ms: int) -> float:
+ return chars / 1_000_000.0 * self.usd_per_million_chars
+
+
+@dataclass(frozen=True, slots=True)
+class GoogleTokenRate:
+ """Billed per token, with Google's own published unit conversions.
+
+ Google prices Gemini speech in tokens and documents both ratios needed to
+ get there, so this is a derivation from published numbers rather than an
+ estimate: "Audio: 32 tokens per second" and "For Gemini models, a token is
+ equivalent to about 4 characters" — https://ai.google.dev/gemini-api/docs/tokens
+ (read 2026-08-24).
+
+ ``usd_per_million_text_tokens`` is 0.0 for a transcription: the audio is
+ the input, and the transcript's output tokens are NOT counted here because
+ the meter deliberately never reads the transcript. That makes a Gemini STT
+ row a documented under-estimate of the audio term rather than a fabricated
+ total — the audio input dominates, and the missing piece is named instead
+ of invented.
+ """
+
+ usd_per_million_audio_tokens: float
+ usd_per_million_text_tokens: float
+ source: str
+
+ #: https://ai.google.dev/gemini-api/docs/tokens — "Audio: 32 tokens per second".
+ AUDIO_TOKENS_PER_SECOND: ClassVar[float] = 32.0
+ #: Same page — "a token is equivalent to about 4 characters".
+ CHARS_PER_TEXT_TOKEN: ClassVar[float] = 4.0
+
+ def usd(self, chars: int, audio_ms: int) -> float:
+ audio_tokens = audio_ms / 1000.0 * self.AUDIO_TOKENS_PER_SECOND
+ text_tokens = chars / self.CHARS_PER_TEXT_TOKEN
+ return (
+ audio_tokens / 1_000_000.0 * self.usd_per_million_audio_tokens
+ + text_tokens / 1_000_000.0 * self.usd_per_million_text_tokens
+ )
+
+
+Rate = MinuteRate | CharRate | GoogleTokenRate
+
+#: Key used inside a provider's table when its price does not depend on the
+#: model or voice at all.
+ANY_MODEL = "*"
+
+# ---------------------------------------------------------------------------
+# Speech-to-text — billed per minute of audio submitted
+# ---------------------------------------------------------------------------
+
+_DEEPGRAM_PRICING = "https://deepgram.com/pricing (read 2026-08-24)"
+_OPENAI_PRICING = "https://developers.openai.com/api/docs/pricing (read 2026-08-24)"
+_GROQ_V3 = "https://console.groq.com/docs/model/whisper-large-v3 (read 2026-08-24)"
+_GROQ_V3_TURBO = (
+ "https://console.groq.com/docs/model/whisper-large-v3-turbo (read 2026-08-24)"
+)
+_GEMINI_PRICING = "https://ai.google.dev/gemini-api/docs/pricing (read 2026-08-24)"
+
+_STT_RATES: dict[str, dict[str, Rate]] = {
+ # jarvis/plugins/stt/deepgram_api.py — the plugin POSTs a complete WAV and
+ # its module docstring says it deliberately does not open the streaming
+ # WebSocket, so the pre-recorded rate is the one that applies, not the
+ # (higher) streaming one. Monolingual; multilingual is $0.0052/min on the
+ # same page, and the plugin does not distinguish the two.
+ "deepgram-api": {
+ "nova-3": MinuteRate(0.0043, _DEEPGRAM_PRICING),
+ },
+ # jarvis/plugins/stt/openai_api.py — DEFAULT_MODEL is whisper-1.
+ "openai-api": {
+ "whisper-1": MinuteRate(0.006, _OPENAI_PRICING), # "$0.006 / minute"
+ "gpt-4o-transcribe": MinuteRate(0.006, _OPENAI_PRICING), # "$0.006 / minute"
+ "gpt-4o-mini-transcribe": MinuteRate(0.003, _OPENAI_PRICING), # "$0.003 / minute"
+ },
+ # jarvis/plugins/stt/groq_api.py — DEFAULT_MODEL is whisper-large-v3.
+ # Groq quotes per hour of audio; /60 for the per-minute rate.
+ "groq-api": {
+ "whisper-large-v3": MinuteRate(0.111 / 60.0, _GROQ_V3), # "$0.111 Per Hour"
+ "whisper-large-v3-turbo": MinuteRate(0.04 / 60.0, _GROQ_V3_TURBO), # "$0.04 Per Hour"
+ },
+ # jarvis/plugins/stt/gemini_api.py — DEFAULT_MODEL is gemini-3-flash-preview,
+ # and the Vertex sibling in the same file (name "vertex-stt") runs the same
+ # models. Audio input is priced separately from text on Google's table.
+ "gemini-api": {
+ "gemini-3-flash-preview": GoogleTokenRate(1.00, 0.0, _GEMINI_PRICING), # audio "$1.00"
+ "gemini-2.5-flash": GoogleTokenRate(1.00, 0.0, _GEMINI_PRICING), # audio "$1.00"
+ },
+ # jarvis/plugins/stt/openrouter_stt.py — OpenRouter resells whichever
+ # upstream serves the model and publishes no flat per-minute audio rate,
+ # so every row here is a gap rather than a guess.
+}
+_STT_RATES["vertex-stt"] = _STT_RATES["gemini-api"]
+
+# ---------------------------------------------------------------------------
+# Text-to-speech — billed per character of input text
+# ---------------------------------------------------------------------------
+
+_ELEVENLABS_PRICING = "https://elevenlabs.io/pricing/api (read 2026-08-24)"
+_INWORLD_PRICING = "https://inworld.ai/pricing (read 2026-08-24)"
+
+_TTS_RATES: dict[str, dict[str, Rate]] = {
+ # jarvis/plugins/tts/elevenlabs_tts.py — DEFAULT_MODEL is eleven_flash_v2_5.
+ # ElevenLabs quotes per 1K characters: Flash/Turbo "$0.05", v2 Multilingual
+ # "$0.10". Models outside those two families (v3, sts, …) are left unknown
+ # rather than assumed to share a tier — the two published tiers differ 2x.
+ "elevenlabs": {
+ "eleven_flash_v2": CharRate(50.0, _ELEVENLABS_PRICING),
+ "eleven_flash_v2_5": CharRate(50.0, _ELEVENLABS_PRICING),
+ "eleven_turbo_v2": CharRate(50.0, _ELEVENLABS_PRICING),
+ "eleven_turbo_v2_5": CharRate(50.0, _ELEVENLABS_PRICING),
+ "eleven_multilingual_v2": CharRate(100.0, _ELEVENLABS_PRICING),
+ },
+ # jarvis/plugins/tts/inworld_tts.py — DEFAULT_MODEL is inworld-tts-2.
+ # On-demand tier: "Realtime TTS-2 $25/1M chars", "Realtime TTS-2 Flash
+ # $15/1M chars". inworld-tts-1 is no longer on the pricing page, so it is
+ # left unknown.
+ "inworld": {
+ "inworld-tts-2": CharRate(25.0, _INWORLD_PRICING),
+ "inworld-tts-2-flash": CharRate(15.0, _INWORLD_PRICING),
+ },
+ # jarvis/plugins/tts/gemini_flash_tts.py — default model
+ # gemini-3.1-flash-tts-preview, sibling bridge gemini-2.5-flash-preview-tts.
+ # Google's table lists these as input (text) / output (audio) per 1M tokens.
+ "gemini-flash-tts": {
+ # "Input: $1.00 (text)" / "Output: $20.00 (audio)"
+ "gemini-3.1-flash-tts-preview": GoogleTokenRate(20.0, 1.00, _GEMINI_PRICING),
+ # "Input: $0.50 (text)" / "Output: $10.00 (audio)"
+ "gemini-2.5-flash-preview-tts": GoogleTokenRate(10.0, 0.50, _GEMINI_PRICING),
+ # "Input: $1.00 (text)" / "Output: $20.00 (audio)"
+ "gemini-2.5-pro-preview-tts": GoogleTokenRate(20.0, 1.00, _GEMINI_PRICING),
+ },
+ # jarvis/plugins/tts/cartesia_tts.py — Cartesia sells monthly credits and
+ # publishes no credit-to-character conversion, so no per-character rate
+ # can be derived from public pricing. Gap, not free.
+ #
+ # jarvis/plugins/tts/grok_voice_tts.py — xAI publishes no public rate for
+ # voice synthesis at all. Gap.
+ #
+ # jarvis/plugins/tts/openrouter_tts.py — priced per speech model by the
+ # upstream that serves it, with no flat published character rate. Gap.
+}
+_TTS_RATES["vertex-tts"] = _TTS_RATES["gemini-flash-tts"]
+
+_TABLES: dict[str, dict[str, dict[str, Rate]]] = {
+ STAGE_STT: _STT_RATES,
+ STAGE_TTS: _TTS_RATES,
+}
+
+
+def find_rate(stage: str, provider: str, model_or_voice: str) -> Rate | None:
+ """The published rate for one (stage, provider, model) triple, or ``None``.
+
+ Matching is exact on a casefolded id — no prefix or family guessing. Two
+ ElevenLabs models one character apart are priced 2x apart, so a near miss
+ has to become a visible gap rather than a plausible wrong number.
+ """
+ table = _TABLES.get((stage or "").strip().casefold(), {})
+ rates = table.get((provider or "").strip().casefold())
+ if not rates:
+ return None
+ return rates.get((model_or_voice or "").strip().casefold()) or rates.get(ANY_MODEL)
+
+
+def price_speech(
+ stage: str,
+ provider: str,
+ model_or_voice: str = "",
+ chars: int = 0,
+ audio_ms: int = 0,
+) -> tuple[float, PriceSource]:
+ """Settle what one metered speech call cost, and how sure that number is.
+
+ The four answers are the ones :func:`jarvis.costs.model.price_entry` uses,
+ with the same meanings:
+
+ ``free`` a local engine — 0.00 is the truth, not a missing rate.
+ ``derived`` re-priced from the published table above.
+ ``recorded`` nothing was consumed, so 0.00 is simply correct.
+ ``unknown`` audio or characters were spent at a rate nobody publishes.
+ 0.00 here is a GAP and the report must show it as one.
+
+ There is deliberately no ``recorded`` path for a real call: unlike a brain
+ response, neither STT nor TTS returns a price with the answer, so a real
+ speech charge is always re-derived or a gap.
+ """
+ used = max(0, chars) + max(0, audio_ms)
+ key = (provider or "").strip().casefold()
+
+ if key in LOCAL_SPEECH_PROVIDERS or key in LOCAL_PROVIDERS:
+ return 0.0, "free"
+
+ if used <= 0:
+ # No audio and no text — a 0.00 with nothing consumed is not a gap.
+ return 0.0, "recorded"
+
+ rate = find_rate(stage, provider, model_or_voice)
+ if rate is None:
+ return 0.0, "unknown"
+ return rate.usd(max(0, chars), max(0, audio_ms)), "derived"
+
+
+__all__ = [
+ "ANY_MODEL",
+ "LOCAL_SPEECH_PROVIDERS",
+ "STAGE_STT",
+ "STAGE_TTS",
+ "CharRate",
+ "GoogleTokenRate",
+ "MinuteRate",
+ "Rate",
+ "find_rate",
+ "price_speech",
+]
diff --git a/jarvis/speech/pipeline.py b/jarvis/speech/pipeline.py
index a0b3094152..4f2306062a 100644
--- a/jarvis/speech/pipeline.py
+++ b/jarvis/speech/pipeline.py
@@ -143,6 +143,8 @@ from jarvis.speech.stt_failure import (
normalize_stt_failure,
stt_failure_message,
)
+from jarvis.speech.usage_meter import meter_stt, meter_tts
+from jarvis.speech.usage_sink import SpeechSpendRecorder
from jarvis.speech.wake_verifier import (
CUSTOM_WAKE_MIN_RMS,
pcm_tail_rms,
@@ -2851,6 +2853,20 @@ class SpeechPipeline:
# Optional event-bus integration. With no bus, transition and emit
# calls are backward-compatible no-ops.
self._bus = bus
+ # Speech spend. The meter wraps the providers rather than the dozen
+ # call sites that use them, so a synthesis added later is counted
+ # without anyone remembering to count it. Only the two that bill are
+ # wrapped: ``self._stt`` is the local wake/VAD Whisper, free and
+ # called many times a second, and metering it would be noise on the
+ # hot path for a number that is always zero.
+ # No bus means nothing can be published, so nothing is wrapped either:
+ # ``meter_*`` hands the provider straight back for a null sink, which
+ # keeps a bus-less pipeline byte-for-byte what it was.
+ self._speech_spend = SpeechSpendRecorder(bus) if bus is not None else None
+ self._tts = meter_tts(self._tts, self._speech_spend, trace_id=self._speech_trace)
+ self._utterance_stt = meter_stt(
+ self._utterance_stt, self._speech_spend, trace_id=self._speech_trace
+ )
self._supervisor = supervisor
# Permanent Vision (Wave 2 B7) is optional. Without an injected
# provider, every vision hook is a no-op.
@@ -3096,8 +3112,10 @@ class SpeechPipeline:
"""
old = type(self._tts).__name__
new = type(new_tts).__name__
- log.info("TTS-Live-Switch: %s -> %s (Caches invalidiert)", old, new)
- self._tts = new_tts
+ log.info("TTS live switch: %s -> %s (caches invalidated)", old, new)
+ # The replacement is metered like the one it replaces, or spend would
+ # stop being recorded the first time someone changed voice.
+ self._tts = meter_tts(new_tts, self._speech_spend, trace_id=self._speech_trace)
self._ack_pcm = b""
self._task_ack_pcm.clear()
@@ -12836,13 +12854,52 @@ class SpeechPipeline:
# two with nothing the user touched explaining it.
translate_to = resolve_translate_target(cfg)
prefix_raw, prefix_text = polished_prefix or ("", "")
+
+ # Prompt Mode outranks both passes: the whole dictation is
+ # rewritten into an English brief for a coding agent, so
+ # neither the formatter nor the translator has anything left
+ # to do — and the incremental prefix, formatted while the
+ # user was still speaking, is superseded by the brief. When
+ # it cannot deliver (no writer, timeout, an answer that is
+ # not a prompt) the dictation falls through to the passes
+ # below exactly as if the switch were off.
+ from jarvis.dictation.prompt_mode import (
+ STATUS_PROMPTED,
+ compose_prompt,
+ prompt_mode_enabled,
+ )
+
+ prompted = False
+ if prompt_mode_enabled(cfg):
+ result = await compose_prompt(
+ cleaned,
+ cfg=cfg,
+ protected_terms=self._dictation_protected_terms(),
+ )
+ prompted = result.status == STATUS_PROMPTED
+ log.info(
+ "dictation prompt mode: %s (%s, %d ms%s).",
+ result.status,
+ result.provider or "no writer",
+ result.latency_ms,
+ f", {result.reason}" if result.reason else "",
+ )
+ if prompted:
+ cleaned = result.text
+ polish_status = result.status
+ polish_provider = result.provider
+ polish_latency_ms = result.latency_ms
+
incremental = bool(
- prefix_raw
+ not prompted
+ and prefix_raw
and not translate_to
and polish_enabled(cfg)
and raw_text.startswith(prefix_raw)
)
- if incremental:
+ if prompted:
+ pass # delivered above; the passes below are superseded
+ elif incremental:
# Only the tail is left: clean it the same way the whole
# text was cleaned above and format it in the light of the
# already-formatted prefix.
@@ -13660,6 +13717,16 @@ class SpeechPipeline:
# returned early) so it cannot leak into the next turn.
self._continuation_pending_drop = None
self._emit_latency_turn_complete()
+ # Close this turn's speech buckets: one priced event per stage and
+ # provider, however many sentences the reply was split into.
+ recorder = getattr(self, "_speech_spend", None)
+ if recorder is not None:
+ recorder.flush()
+
+ def _speech_trace(self) -> str:
+ """The turn a metered speech call belongs to, or "" between turns."""
+ tracker = getattr(self, "_latency_tracker", None)
+ return str(getattr(tracker, "trace_id", "") or "")
def _emit_latency_turn_complete(self) -> None:
"""Fire-and-forget flush of this turn's stage snapshot.
diff --git a/jarvis/speech/stt_dictionary.py b/jarvis/speech/stt_dictionary.py
index 4471701548..7f5843d04a 100644
--- a/jarvis/speech/stt_dictionary.py
+++ b/jarvis/speech/stt_dictionary.py
@@ -487,7 +487,13 @@ class DictionaryCorrectingSTT:
naming which provider actually ran — the one fact you need when a
provider is the thing failing, which is exactly when someone reads it.
"""
- inner = getattr(self._inner, "provider_label", "")
+ inner = getattr(self._inner, "provider_label", "") or getattr(
+ self._inner, "name", ""
+ )
+ # ``name`` before the class name: every provider carries the id the
+ # rest of the app knows it by ("groq-api"), and a log line naming
+ # ``GroqWhisperAPI`` answers a question nobody asked. The class name
+ # stays as the last resort for an object that has neither.
return str(inner) if inner else type(self._inner).__name__
def __getattr__(self, name: str) -> Any:
diff --git a/jarvis/speech/usage_meter.py b/jarvis/speech/usage_meter.py
new file mode 100644
index 0000000000..af93203d90
--- /dev/null
+++ b/jarvis/speech/usage_meter.py
@@ -0,0 +1,440 @@
+"""Meter what speech spends — without ever standing in the way of speech.
+
+Speech-to-text and text-to-speech do not bill by token, so nothing on the
+model-cost path sees them: STT is billed per minute of audio, TTS per
+character of input. Neither number is recorded anywhere in the app today,
+which is why the Spend section's speech row is permanently empty.
+
+Instrumenting call sites would not fix that. ``synthesize`` alone is called
+from ten places in :mod:`jarvis.speech.pipeline` and more outside it, and the
+eleventh call site — the one somebody adds next month — would silently miss.
+So the *provider* is wrapped instead: one decorator per protocol, applied once
+where the provider is built, and every call site is covered, including the
+ones that do not exist yet.
+
+Three properties are non-negotiable, in this order:
+
+**It never delays speech.** Measuring is arithmetic on values already in hand:
+``len(text)``, and the length of the PCM a chunk already carries. The sink is
+called synchronously and nothing here awaits it (AP-9). The wrappers are
+straight pass-throughs — a chunk is yielded onward the moment it arrives, and
+no audio is ever buffered.
+
+**It never breaks speech.** A sink that raises, a provider attribute that is
+missing, a clock that misbehaves — all of it is caught and logged, and the
+utterance continues. A metering bug that silenced Jarvis would be a far worse
+bug than the missing ledger it was written to fix.
+
+**It reports what was actually spent, not what completed.** A cancelled turn
+that sent 400 characters to ElevenLabs spent those 400 characters, and a
+transcription abandoned mid-stream still consumed the audio the provider read.
+Every measured call reports from a ``finally``, so an abandoned generator, a
+cancellation and an exception all still reach the ledger.
+
+Wrapping is free when nothing is listening: ``meter_tts(provider, None)``
+returns the very same object, so an install with no cost sink pays nothing —
+not an attribute lookup, not a stack frame.
+
+Pricing lives next door in :mod:`jarvis.costs.speech_rates`; this module only
+counts. Nothing here initialises at import time (AP-26).
+"""
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import AsyncIterator, Callable
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+log = logging.getLogger(__name__)
+
+STAGE_STT = "stt"
+STAGE_TTS = "tts"
+
+#: Every PCM buffer that crosses this app is signed 16-bit — the STT
+#: protocol says so (``detect_end_of_turn`` returns "raw int16 PCM bytes")
+#: and every plugin honours it. Two bytes per sample per channel.
+BYTES_PER_SAMPLE = 2
+
+#: Fallback when a caller hands ``transcribe_pcm`` bytes without naming the
+#: rate. It is the default in every shipped STT plugin's own signature, so
+#: assuming it here reproduces exactly what the provider itself assumed.
+DEFAULT_PCM_SAMPLE_RATE = 16_000
+
+
+@dataclass(frozen=True, slots=True)
+class SpeechUsage:
+ """One metered speech call.
+
+ ``chars`` and ``audio_ms`` are both filled whenever they are knowable,
+ because which one bills depends on the vendor and we do not want the
+ pricing table's answer baked into the measurement. TTS bills on ``chars``
+ and reports ``audio_ms`` as the by-product; STT bills on ``audio_ms`` and
+ leaves ``chars`` at 0 — deliberately, since counting transcript characters
+ would mean reading the user's words to price them.
+
+ ``model_or_voice`` is the identifier that actually decides the rate: the
+ model for STT, and for TTS the model where the provider exposes one (an
+ ElevenLabs Flash character costs half a Multilingual one) falling back to
+ the voice, which is all some providers publish.
+ """
+
+ stage: str
+ provider: str
+ model_or_voice: str
+ chars: int
+ audio_ms: int
+ ts_ms: int
+ trace_id: str
+
+
+@runtime_checkable
+class UsageSink(Protocol):
+ """Where a metered call is reported.
+
+ Deliberately synchronous. The meter runs inside a ``finally`` that may be
+ executing during ``GeneratorExit``, where awaiting is illegal, and on the
+ voice critical path, where awaiting is forbidden anyway (AP-9). An
+ implementation that needs I/O queues the record and returns.
+ """
+
+ def record(self, usage: SpeechUsage) -> None:
+ """Take one usage record. Must not block and must not raise."""
+ ...
+
+
+#: A fixed id, or something that answers with the id of the turn in flight.
+TraceIdSource = str | Callable[[], str] | None
+
+
+def pcm_duration_ms(pcm: bytes, sample_rate: int, channels: int = 1) -> float:
+ """Milliseconds of audio in a raw int16 PCM buffer.
+
+ Fractional on purpose. A TTS chunk is often a few tens of milliseconds, so
+ truncating each one to a whole millisecond before summing loses close to a
+ second over a long answer — the caller rounds once, at the end.
+ """
+ if not pcm or sample_rate <= 0:
+ return 0.0
+ frame_bytes = BYTES_PER_SAMPLE * max(1, channels)
+ return len(pcm) / frame_bytes / sample_rate * 1000.0
+
+
+def _chunk_ms(chunk: Any) -> float:
+ """Duration of one :class:`~jarvis.core.protocols.AudioChunk`.
+
+ Read through ``getattr`` so a provider that yields its own chunk-shaped
+ object — or a test fake — is measured rather than crashed on.
+ """
+ return pcm_duration_ms(
+ getattr(chunk, "pcm", b"") or b"",
+ int(getattr(chunk, "sample_rate", 0) or 0),
+ int(getattr(chunk, "channels", 1) or 1),
+ )
+
+
+class _CountingAudio:
+ """Passes an ``AudioChunk`` stream through, adding up what was consumed.
+
+ The provider gets a stream that behaves exactly like the one the caller
+ handed over; the total is whatever the provider actually pulled, so a
+ provider that stops early is billed for what it read.
+ """
+
+ __slots__ = ("_source", "audio_ms")
+
+ def __init__(self, source: AsyncIterator[Any]) -> None:
+ self._source = source
+ self.audio_ms = 0.0
+
+ def __aiter__(self) -> _CountingAudio:
+ return self
+
+ async def __anext__(self) -> Any:
+ chunk = await self._source.__anext__()
+ self.audio_ms += _chunk_ms(chunk)
+ return chunk
+
+
+class _MeteredProvider:
+ """Attribute forwarding and reporting shared by both wrappers.
+
+ Everything the concrete provider exposes stays reachable: ``__getattr__``
+ forwards the rest of its surface (``transcribe_container``,
+ ``last_used_model``, ``recover``, a provider-specific method added
+ tomorrow) so wrapping cannot quietly remove a capability someone probes
+ for with ``hasattr``.
+ """
+
+ _stage = ""
+
+ def __init__(
+ self,
+ provider: Any,
+ sink: UsageSink,
+ *,
+ trace_id: TraceIdSource = None,
+ ) -> None:
+ self._inner = provider
+ self._sink = sink
+ self._trace_id = trace_id
+ self._sink_broken = False
+ # Copied rather than delegated: the protocol declares both as plain
+ # attributes, and every shipped provider sets them once as class
+ # constants. This mirrors ``FallbackTTS``, which does the same.
+ self.name: str = str(getattr(provider, "name", "") or "")
+ self.supports_streaming: bool = bool(getattr(provider, "supports_streaming", False))
+
+ def __getattr__(self, name: str) -> Any:
+ # ``_inner`` is bound first in __init__; guarding it stops a path that
+ # bypasses __init__ (copy, pickle) from recursing forever.
+ if name == "_inner":
+ raise AttributeError(name)
+ return getattr(self._inner, name)
+
+ def __repr__(self) -> str: # pragma: no cover — logging nicety
+ return f"{type(self).__name__}({self.name or type(self._inner).__name__})"
+
+ def _report(self, *, model_or_voice: str, chars: int, audio_ms: float) -> None:
+ """Hand one record to the sink. Never raises, never blocks.
+
+ Called from a ``finally``, which may be running during
+ ``GeneratorExit`` — so this is synchronous throughout.
+ """
+ try:
+ trace = self._trace_id
+ trace_id = str(trace() or "") if callable(trace) else str(trace or "")
+ self._sink.record(
+ SpeechUsage(
+ stage=self._stage,
+ provider=self._provider_label(),
+ model_or_voice=model_or_voice,
+ chars=max(0, chars),
+ audio_ms=max(0, round(audio_ms)),
+ ts_ms=int(time.time() * 1000),
+ trace_id=trace_id,
+ )
+ )
+ except Exception as exc:
+ # Silence is right here, and it is the whole point of the module:
+ # accounting must never cost an utterance (AP-9/AP-30). The first
+ # failure is loud enough to find, the rest are debug so a broken
+ # sink cannot flood the log during a live conversation.
+ if not self._sink_broken:
+ self._sink_broken = True
+ log.warning(
+ "Speech usage sink failed (%s: %s); metering continues, records are lost.",
+ type(exc).__name__, exc,
+ )
+ else:
+ log.debug("Speech usage sink failed again (%s).", exc)
+
+ def _provider_label(self) -> str:
+ """Who actually did the work.
+
+ ``FallbackTTS`` answers to the primary's ``name`` even when the backup
+ spoke, ``FallbackSTT`` delegates ``name`` to its primary, and Cartesia
+ and ElevenLabs each fall back internally as well. Every one of them
+ records the vendor that really ran — ``last_voice_provider`` on the TTS
+ side, ``last_used_provider`` on the STT side — so the ledger names the
+ vendor that was billed rather than the one that was asked.
+ """
+ for attr in ("last_voice_provider", "last_used_provider"):
+ spoke = getattr(self._inner, attr, None)
+ if spoke:
+ return str(spoke)
+ return self.name
+
+
+class MeteredTTS(_MeteredProvider):
+ """A :class:`~jarvis.core.protocols.TTSProvider` that counts characters."""
+
+ _stage = STAGE_TTS
+
+ # NOT ``async def`` returning a coroutine: every implementation is an async
+ # GENERATOR, and both calling conventions are live in the pipeline —
+ # ``chunks = tts.synthesize(text, language_code=lang)`` with no await, and
+ # ``async for c in tts.synthesize(phrase)``. Declaring this as a generator
+ # too keeps both working and keeps the stream lazy: nothing runs until the
+ # first ``__anext__``, and each chunk is forwarded the instant it arrives.
+ async def synthesize(
+ self,
+ text: str,
+ voice: str | None = None,
+ language_code: str | None = None,
+ **extra: Any,
+ ) -> AsyncIterator[Any]:
+ """Forward the synthesis, counting the input characters exactly once.
+
+ ``**extra`` is forwarded untouched so a provider-specific keyword still
+ reaches the provider, and the optional keywords are only passed on when
+ the caller actually gave them — a third-party plugin with a narrower
+ signature keeps working.
+ """
+ chars = len(text or "")
+ kwargs: dict[str, Any] = dict(extra)
+ if voice is not None:
+ kwargs["voice"] = voice
+ if language_code is not None:
+ kwargs["language_code"] = language_code
+
+ audio_ms = 0.0
+ try:
+ async for chunk in self._inner.synthesize(text, **kwargs):
+ audio_ms += _chunk_ms(chunk)
+ yield chunk
+ finally:
+ # Reached on exhaustion, on an exception, on cancellation, and on
+ # the ``aclose()`` of a generator the caller walked away from. The
+ # characters left the building when the request did.
+ self._report(
+ model_or_voice=self._tts_rate_key(voice),
+ chars=chars,
+ audio_ms=audio_ms,
+ )
+
+ def _tts_rate_key(self, voice: str | None) -> str:
+ """The identifier the TTS rate actually depends on.
+
+ The model where the provider has one — ElevenLabs Flash and
+ Multilingual differ by 2x on the same voice — and the voice otherwise,
+ which is the only handle Cartesia and Grok expose. ``_model`` /
+ ``_model_name`` are private by the plugins' own convention; reading
+ them is deliberate and degrades to the voice when they are absent.
+ """
+ for attr in ("last_used_model", "_model", "_model_name"):
+ value = getattr(self._inner, attr, None)
+ if value:
+ return str(value)
+ spoken = getattr(self._inner, "last_voice", None)
+ return str(spoken or voice or "")
+
+
+class MeteredSTT(_MeteredProvider):
+ """An :class:`~jarvis.core.protocols.STTProvider` that counts audio time."""
+
+ _stage = STAGE_STT
+
+ async def transcribe(self, audio: AsyncIterator[Any], *args: Any, **kwargs: Any) -> Any:
+ counter = _CountingAudio(audio)
+ try:
+ return await self._inner.transcribe(counter, *args, **kwargs)
+ finally:
+ self._report(
+ model_or_voice=self._stt_rate_key(),
+ chars=0,
+ audio_ms=counter.audio_ms,
+ )
+
+ # An async generator for the same reason ``synthesize`` is one: the
+ # implementations are generators, callers iterate the return value without
+ # awaiting it, and partials must keep arriving as they are produced.
+ async def stream_transcribe(
+ self, audio: AsyncIterator[Any], *args: Any, **kwargs: Any
+ ) -> AsyncIterator[Any]:
+ counter = _CountingAudio(audio)
+ try:
+ async for transcript in self._inner.stream_transcribe(counter, *args, **kwargs):
+ yield transcript
+ finally:
+ self._report(
+ model_or_voice=self._stt_rate_key(),
+ chars=0,
+ audio_ms=counter.audio_ms,
+ )
+
+ def __getattr__(self, name: str) -> Any:
+ # ``transcribe_pcm`` is the path the live microphone really takes —
+ # every shipped plugin has it and ``pipeline`` calls it, not
+ # ``transcribe`` — but it is NOT on the protocol, so it is metered
+ # here rather than declared. Resolving it through the inner provider
+ # first keeps ``hasattr`` honest for a provider that lacks it.
+ if name == "transcribe_pcm":
+ if not hasattr(self._inner, "transcribe_pcm"):
+ raise AttributeError(name)
+ return self._metered_transcribe_pcm
+ return super().__getattr__(name)
+
+ async def _metered_transcribe_pcm(
+ self, pcm_bytes: bytes, *args: Any, **kwargs: Any
+ ) -> Any:
+ """Meter the VAD-segmented-utterance path.
+
+ The shared signature across every plugin is
+ ``transcribe_pcm(pcm_bytes, sample_rate=16_000, language=None, ...)``,
+ so the rate is either the first positional extra or the keyword; the
+ rest is forwarded untouched, including the arguments only one plugin
+ takes (faster-whisper's ``ignore_initial_prompt``).
+ """
+ rate = int(args[0]) if args else int(kwargs.get("sample_rate", DEFAULT_PCM_SAMPLE_RATE))
+ audio_ms = pcm_duration_ms(pcm_bytes or b"", rate)
+ try:
+ return await self._inner.transcribe_pcm(pcm_bytes, *args, **kwargs)
+ finally:
+ self._report(
+ model_or_voice=self._stt_rate_key(),
+ chars=0,
+ audio_ms=audio_ms,
+ )
+
+ def _stt_rate_key(self) -> str:
+ """The model that priced this transcription.
+
+ Read after the call: every cloud plugin narrows or falls back on a
+ rejected model and records the result on ``last_used_model``, so the
+ effective model is the one the invoice will show.
+ """
+ for attr in ("last_used_model", "_model", "_model_name"):
+ value = getattr(self._inner, attr, None)
+ if value:
+ return str(value)
+ return ""
+
+
+def meter_tts(provider: Any, sink: UsageSink | None, *, trace_id: TraceIdSource = None) -> Any:
+ """Wrap a TTS provider so every ``synthesize`` lands in the ledger.
+
+ Returns ``provider`` itself when there is nothing to report to, or when it
+ is already wrapped — an install without a cost sink pays nothing at all.
+
+ Typed ``Any`` in and ``Any`` out, like ``wrap_stt_with_dictionary`` next
+ door and for the same reason: ``TTSProvider.synthesize`` is declared with
+ ``async def`` while every implementation (including this wrapper) is an
+ async generator, so the nominal type does not describe the real contract.
+ """
+ if provider is None or sink is None or isinstance(provider, MeteredTTS):
+ return provider
+ return MeteredTTS(provider, sink, trace_id=trace_id)
+
+
+def meter_stt(provider: Any, sink: UsageSink | None, *, trace_id: TraceIdSource = None) -> Any:
+ """Wrap an STT provider so every transcription lands in the ledger.
+
+ Covers ``transcribe``, ``stream_transcribe`` and ``transcribe_pcm``.
+ ``transcribe_container`` — the UltraWiki path for an already-encoded voice
+ note — is forwarded unmetered: its duration is not derivable without
+ decoding the container, and decoding to price it is exactly the kind of
+ work that must never appear here.
+
+ Returns ``provider`` itself when ``sink`` is ``None`` or it is already
+ wrapped.
+ """
+ if provider is None or sink is None or isinstance(provider, MeteredSTT):
+ return provider
+ return MeteredSTT(provider, sink, trace_id=trace_id)
+
+
+__all__ = [
+ "BYTES_PER_SAMPLE",
+ "DEFAULT_PCM_SAMPLE_RATE",
+ "STAGE_STT",
+ "STAGE_TTS",
+ "MeteredSTT",
+ "MeteredTTS",
+ "SpeechUsage",
+ "TraceIdSource",
+ "UsageSink",
+ "meter_stt",
+ "meter_tts",
+ "pcm_duration_ms",
+]
diff --git a/jarvis/speech/usage_sink.py b/jarvis/speech/usage_sink.py
new file mode 100644
index 0000000000..58ecc45335
--- /dev/null
+++ b/jarvis/speech/usage_sink.py
@@ -0,0 +1,126 @@
+"""Turn metered speech calls into one priced event per turn.
+
+:mod:`jarvis.speech.usage_meter` reports every individual call: a streaming
+reply is synthesised sentence by sentence, so a single spoken answer can be
+fifteen of them. Fifteen rows a turn is exactly the kind of chatty stream the
+session recorder deliberately keeps out, and none of them is interesting on
+its own — what anyone wants to know is what the turn cost.
+
+So this sums them per (stage, provider, voice) while a turn is in flight and
+publishes once, priced, when the turn ends. Two rows a turn, whatever happened
+inside it.
+
+AP-9: nothing here may sit on the voice critical path. ``record`` is
+arithmetic on a dict and returns; the publish is a fire-and-forget task, and
+every failure is swallowed with a log — telemetry never breaks a turn.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from jarvis.core.events import SpeechUsageRecorded
+from jarvis.costs.speech_rates import price_speech
+
+from .usage_meter import SpeechUsage
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class _Bucket:
+ """One (stage, provider, voice) within one turn."""
+
+ chars: int = 0
+ audio_ms: int = 0
+ ts_ms: int = 0
+
+
+class SpeechSpendRecorder:
+ """A :class:`~jarvis.speech.usage_meter.UsageSink` that publishes per turn.
+
+ Buckets are keyed by trace id as well, so a usage record arriving for a
+ new turn flushes the previous one on its own. An explicit :meth:`flush`
+ at the end of a turn is still the normal path — this is the safety net for
+ a turn that ended in a way that never reached it.
+ """
+
+ def __init__(self, bus: Any | None) -> None:
+ """``bus`` is anything with an awaitable ``publish`` — typed loosely so
+ this module never drags the bus implementation onto the import path."""
+ self._bus = bus
+ self._trace = ""
+ self._buckets: dict[tuple[str, str, str], _Bucket] = {}
+
+ # -- UsageSink ---------------------------------------------------------
+
+ def record(self, usage: SpeechUsage) -> None:
+ """Take one metered call. Must not block and must not raise."""
+ try:
+ if usage.trace_id and usage.trace_id != self._trace:
+ # A new turn began without anyone flushing the last one.
+ self.flush()
+ self._trace = usage.trace_id
+ key = (usage.stage, usage.provider, usage.model_or_voice)
+ slot = self._buckets.get(key)
+ if slot is None:
+ slot = _Bucket(ts_ms=usage.ts_ms or int(time.time() * 1000))
+ self._buckets[key] = slot
+ slot.chars += max(0, usage.chars)
+ slot.audio_ms += max(0, usage.audio_ms)
+ except Exception: # noqa: BLE001 — a meter must never break a turn
+ log.debug("speech usage record failed", exc_info=True)
+
+ # -- turn boundary -----------------------------------------------------
+
+ def flush(self) -> None:
+ """Publish what this turn spent, one event per stage and provider."""
+ if not self._buckets:
+ return
+ buckets, self._buckets = self._buckets, {}
+ trace = self._trace
+ for (stage, provider, voice), slot in buckets.items():
+ try:
+ cost, source = price_speech(
+ stage,
+ provider,
+ voice,
+ chars=slot.chars,
+ audio_ms=slot.audio_ms,
+ )
+ self._publish(
+ SpeechUsageRecorded(
+ trace_id=trace,
+ source_layer="speech.usage",
+ stage=stage,
+ provider=provider,
+ voice=voice,
+ chars=slot.chars,
+ audio_ms=float(slot.audio_ms),
+ cost_usd=cost,
+ price_source=source,
+ )
+ )
+ except Exception: # noqa: BLE001 — see the module docstring
+ log.debug("speech usage flush failed", exc_info=True)
+
+ def _publish(self, event: SpeechUsageRecorded) -> None:
+ bus = self._bus
+ if bus is None:
+ return
+ try:
+ loop = asyncio.get_running_loop()
+ except RuntimeError:
+ # Flushed from a thread with no loop — the turn is over and there
+ # is nothing to await on. Dropping one row beats raising into a
+ # caller that is shutting the pipeline down.
+ log.debug("speech usage: no running loop, dropping %s", event.stage)
+ return
+ loop.create_task(bus.publish(event)) # noqa: RUF006 — fire-and-forget
+
+
+__all__ = ["SpeechSpendRecorder"]
diff --git a/jarvis/ui/web/costs_routes.py b/jarvis/ui/web/costs_routes.py
index 95cf2632a0..e2c6509e87 100644
--- a/jarvis/ui/web/costs_routes.py
+++ b/jarvis/ui/web/costs_routes.py
@@ -209,6 +209,7 @@ class _EntryCache:
return self._entries
# The coding-CLI source pre-aggregates, so it has to know the grain
# the report will draw at before it reads a row.
+ _refresher.nudge(sources.cli_index_dir)
entries = collect_entries(
sources,
since_ms=since_ms,
@@ -225,6 +226,67 @@ class _EntryCache:
_cache = _EntryCache()
+# ---------------------------------------------------------------------------
+# The coding-CLI index — kept current in the background, never in a request
+# ---------------------------------------------------------------------------
+
+
+class _IndexRefresher:
+ """Nudges :mod:`jarvis.costs.cli_usage_index` forward on its own thread.
+
+ Reading a vendor transcript is seconds of I/O on gigabytes, so it can
+ never happen while a request waits. Instead every summary request asks
+ this to run, and it does so at most once a minute, one thread at a time,
+ reporting whatever it managed. The section always renders from what the
+ index already has; a first run on a busy machine simply fills in over the
+ next few refreshes rather than blocking the page (AP-26: nothing here
+ starts at import or at boot either — the first request arms it).
+ """
+
+ _MIN_GAP_S = 60.0
+ _BUDGET_S = 20.0
+
+ def __init__(self) -> None:
+ self._lock = threading.Lock()
+ self._running = False
+ self._last = 0.0
+
+ def nudge(self, data_dir: Path | None) -> None:
+ now = time.monotonic()
+ with self._lock:
+ if self._running or (self._last and now - self._last < self._MIN_GAP_S):
+ return
+ self._running = True
+ threading.Thread(
+ target=self._run, args=(data_dir,), name="cli-usage-index", daemon=True
+ ).start()
+
+ def _run(self, data_dir: Path | None) -> None:
+ try:
+ from jarvis.costs.cli_usage_index import refresh
+
+ result = refresh(data_dir=data_dir, deadline_s=self._BUDGET_S)
+ if result.turns_added:
+ log.debug(
+ "cli usage index: +%d turns from %d files",
+ result.turns_added,
+ result.files_scanned,
+ )
+ except Exception as exc: # noqa: BLE001 — a background index must never
+ # take the section down with it; the report just stays as current
+ # as the last successful run.
+ log.warning("cli usage index: refresh failed (%s)", exc)
+ finally:
+ with self._lock:
+ self._running = False
+ self._last = time.monotonic()
+
+
+_refresher = _IndexRefresher()
+
+
+
+
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
diff --git a/jarvis/ui/web/frontend/src/views/CostsView.tsx b/jarvis/ui/web/frontend/src/views/CostsView.tsx
index ff99a5e22e..53ddb25e0c 100644
--- a/jarvis/ui/web/frontend/src/views/CostsView.tsx
+++ b/jarvis/ui/web/frontend/src/views/CostsView.tsx
@@ -335,7 +335,14 @@ export function CostsView() {
<StatTile
icon={<AlertTriangle className="h-4 w-4" />}
label={t("costs_view.stat_gap")}
- value={formatTokens(totals?.gap_tokens ?? 0)}
+ // A gap in the speech layer spends characters, not tokens, so
+ // its token count is a truthful zero. Fall back to naming the
+ // calls, or the tile would report "0 unpriced" while warning.
+ value={
+ (totals?.gap_tokens ?? 0) > 0
+ ? formatTokens(totals?.gap_tokens ?? 0)
+ : formatExact(totals?.gap_entries ?? 0)
+ }
hint={
(totals?.gap_tokens ?? 0) > 0
? fill(t("costs_view.stat_gap_hint"), {
diff --git a/tests/unit/speech/test_usage_meter.py b/tests/unit/speech/test_usage_meter.py
new file mode 100644
index 0000000000..b5b868f019
--- /dev/null
+++ b/tests/unit/speech/test_usage_meter.py
@@ -0,0 +1,228 @@
+"""The speech meter must count without ever being felt.
+
+It sits on the voice critical path (AP-9), so the properties that matter are
+as much about what it does NOT do — buffer, block, raise, or hide a provider's
+surface — as about the numbers it reports.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+import pytest
+
+from jarvis.core.protocols import AudioChunk
+from jarvis.speech.usage_meter import (
+ SpeechUsage,
+ meter_stt,
+ meter_tts,
+ pcm_duration_ms,
+)
+
+# 16-bit mono at 16 kHz: 32 bytes = 1 ms.
+_RATE = 16_000
+_MS = b"\x00" * 32
+
+
+class _Sink:
+ def __init__(self) -> None:
+ self.records: list[SpeechUsage] = []
+
+ def record(self, usage: SpeechUsage) -> None:
+ self.records.append(usage)
+
+
+class _AngrySink:
+ """A sink that fails every time — the meter must absorb it."""
+
+ def record(self, usage: SpeechUsage) -> None:
+ raise RuntimeError("sink is down")
+
+
+class _FakeTTS:
+ name = "cartesia"
+ supports_streaming = True
+
+ def __init__(self, chunks: int = 3) -> None:
+ self._chunks = chunks
+ self.calls: list[tuple[str, str | None]] = []
+
+ async def synthesize(
+ self,
+ text: str,
+ voice: str | None = None,
+ language_code: str | None = None,
+ ) -> AsyncIterator[AudioChunk]:
+ self.calls.append((text, voice))
+ for _ in range(self._chunks):
+ yield AudioChunk(pcm=_MS * 100, sample_rate=_RATE, timestamp_ns=0)
+
+ def list_voices(self, language: str | None = None) -> list[str]:
+ return ["ben", "nova"]
+
+ def some_provider_specific_thing(self) -> str:
+ return "still here"
+
+
+class _FakeSTT:
+ name = "deepgram-api"
+ supports_streaming = False
+
+ def __init__(self) -> None:
+ self.seen = 0
+
+ async def transcribe(self, audio: AsyncIterator[AudioChunk]) -> str:
+ async for _chunk in audio:
+ self.seen += 1
+ return "hello"
+
+
+async def _audio(chunks: int) -> AsyncIterator[AudioChunk]:
+ for _ in range(chunks):
+ yield AudioChunk(pcm=_MS * 250, sample_rate=_RATE, timestamp_ns=0)
+
+
+# ---------------------------------------------------------------------------
+# Measuring
+# ---------------------------------------------------------------------------
+
+
+def test_pcm_duration_is_bytes_over_rate() -> None:
+ assert pcm_duration_ms(_MS * 500, _RATE) == pytest.approx(500.0)
+ assert pcm_duration_ms(b"", _RATE) == 0.0
+
+
+async def test_tts_counts_the_text_it_was_given() -> None:
+ sink = _Sink()
+ tts = meter_tts(_FakeTTS(), sink)
+
+ async for _chunk in tts.synthesize("hallo welt", voice="ben"):
+ pass
+
+ (usage,) = sink.records
+ assert usage.stage == "tts"
+ assert usage.provider == "cartesia"
+ assert usage.chars == len("hallo welt")
+ # The audio it produced is reported too, as the by-product it is.
+ assert usage.audio_ms == pytest.approx(300, abs=1)
+
+
+async def test_tts_reports_once_per_call_not_once_per_chunk() -> None:
+ sink = _Sink()
+ tts = meter_tts(_FakeTTS(chunks=12), sink)
+
+ async for _chunk in tts.synthesize("x" * 40):
+ pass
+
+ assert len(sink.records) == 1
+
+
+async def test_stt_counts_the_audio_it_consumed() -> None:
+ sink = _Sink()
+ stt = meter_stt(_FakeSTT(), sink)
+
+ assert await stt.transcribe(_audio(4)) == "hello"
+
+ (usage,) = sink.records
+ assert usage.stage == "stt"
+ assert usage.audio_ms == pytest.approx(1000, abs=1)
+ # Counting transcript characters would mean reading the user's words
+ # in order to bill them.
+ assert usage.chars == 0
+
+
+# ---------------------------------------------------------------------------
+# Never felt
+# ---------------------------------------------------------------------------
+
+
+async def test_synthesis_is_lazy() -> None:
+ """The first chunk must arrive before the stream ends, or the meter has
+ buffered the whole reply and added latency to every spoken word."""
+ sink = _Sink()
+ tts = meter_tts(_FakeTTS(chunks=5), sink)
+
+ stream = tts.synthesize("hallo")
+ first = await stream.__anext__()
+
+ assert first.sample_rate == _RATE
+ assert sink.records == [] # nothing reported yet — the call is still open
+ await stream.aclose()
+
+
+async def test_an_abandoned_stream_still_reports() -> None:
+ """A cancelled turn that spent 400 characters spent them."""
+ sink = _Sink()
+ tts = meter_tts(_FakeTTS(chunks=99), sink)
+
+ stream = tts.synthesize("y" * 400)
+ await stream.__anext__()
+ await stream.aclose()
+
+ (usage,) = sink.records
+ assert usage.chars == 400
+
+
+async def test_a_failing_sink_never_breaks_synthesis() -> None:
+ tts = meter_tts(_FakeTTS(), _AngrySink())
+
+ chunks = [c async for c in tts.synthesize("hallo")]
+
+ assert len(chunks) == 3
+
+
+async def test_no_sink_returns_the_provider_untouched() -> None:
+ """Zero cost when nobody is listening — not even a wrapper object."""
+ provider = _FakeTTS()
+ assert meter_tts(provider, None) is provider
+ stt = _FakeSTT()
+ assert meter_stt(stt, None) is stt
+
+
+# ---------------------------------------------------------------------------
+# Nothing of the provider may go missing
+# ---------------------------------------------------------------------------
+
+
+def test_the_protocol_surface_survives_wrapping() -> None:
+ tts = meter_tts(_FakeTTS(), _Sink())
+
+ assert tts.name == "cartesia"
+ assert tts.supports_streaming is True
+ assert tts.list_voices() == ["ben", "nova"]
+ # Anything the concrete provider adds stays reachable, or a `hasattr`
+ # probe somewhere quietly loses a capability.
+ assert tts.some_provider_specific_thing() == "still here"
+
+
+async def test_arguments_reach_the_provider_unchanged() -> None:
+ provider = _FakeTTS()
+ tts = meter_tts(provider, _Sink())
+
+ async for _chunk in tts.synthesize("guten tag", voice="nova"):
+ pass
+
+ assert provider.calls == [("guten tag", "nova")]
+
+
+async def test_the_trace_id_of_the_turn_is_carried() -> None:
+ sink = _Sink()
+ turn = {"id": "trace-1"}
+ tts = meter_tts(_FakeTTS(), sink, trace_id=lambda: turn["id"])
+
+ async for _chunk in tts.synthesize("eins"):
+ pass
+ turn["id"] = "trace-2"
+ async for _chunk in tts.synthesize("zwei"):
+ pass
+
+ assert [u.trace_id for u in sink.records] == ["trace-1", "trace-2"]