pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/providers/prices.py

@@ -0,0 +1,240 @@
+"""What a call's usage cost in US dollars, from the rates of the box's configuration."""
+
+import csv
+import math
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from pinecall.domain.call import PhoneLeg
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.providers.catalog import Providers, Rate, longest_prefix
+from pinecall.wire.metrics import LLMModelUsage, ModelUsage, STTModelUsage, TTSModelUsage
+from pinecall.wire.parts import PLATFORM, Cost, CostRow, UnpricedRow
+
+type Unit = Literal["input_tokens", "cached_input_tokens", "cache_creation_tokens", "output_tokens"]
+
+
+A_MILLION = 1_000_000
+
+A_MINUTE_S = 60
+
+# A prices file's unit, and the field of `Rate` it fills.
+FIELD_OF_UNIT = {
+    "input_tokens": "input",
+    "output_tokens": "output",
+    "cached_input_tokens": "cached_input",
+    "cache_creation_tokens": "cache_creation",
+    "characters": "characters",
+    "audio_seconds": "audio_seconds",
+    "minutes": "minutes",
+}
+
+COLUMNS = ("vendor", "model", "unit", "usd", "as_of", "source")
+
+# The box's own compute, priced by the operator as `pinecall,pinecall-compute,minutes,<usd>` in
+# the prices file: a call's seconds on the worker, every one counted, never minutes begun. With no
+# such row nothing is priced and nothing is listed: a box that never priced itself is not unpriced.
+COMPUTE = "pinecall-compute"
+
+
+@dataclass(frozen=True)
+class RatesChange:
+    """What writing a prices file would do to the box's rates, model by model."""
+
+    added: tuple[str, ...]
+    changed: tuple[str, ...]
+    unchanged: tuple[str, ...]
+    # Kept as they are: a file adds and replaces, it never removes.
+    only_on_the_box: tuple[str, ...]
+
+
+def cost(
+    usage: Iterable[ModelUsage],
+    configured: Providers,
+    *,
+    legs: Sequence[PhoneLeg] = (),
+    seconds: float = 0.0,
+) -> Cost:
+    """Price every usage row, phone leg and the call's seconds of compute; no rate is unpriced."""
+    rows: list[CostRow] = []
+    unpriced: list[UnpricedRow] = []
+    for used in usage:
+        priced = _priced(used, configured.rates)
+        if priced is None:
+            unpriced.append(UnpricedRow(provider=used.provider, model=used.model))
+        else:
+            rows += priced
+    for leg in legs:
+        billed = _leg_row(leg, configured.rates)
+        if billed is None:
+            unpriced.append(UnpricedRow(provider=leg.carrier, model=_leg_name(leg)))
+        elif billed.quantity > 0:
+            rows.append(billed)
+    compute = _compute_row(seconds, configured.rates)
+    if compute is not None:
+        rows.append(compute)
+    return Cost(usd=round(sum(row.usd for row in rows), 6), rows=rows, unpriced=unpriced)
+
+
+def rate_of(rates: Mapping[str, Rate], model: str) -> Rate | None:
+    """The rate whose key is the longest prefix of the model id, so snapshots price by family."""
+    key = longest_prefix(rates, model)
+    return None if key is None else rates[key]
+
+
+def rates_from_csv(text: str) -> dict[str, Rate]:
+    """The rates of a prices file, one row per model and unit; `#` lines are notes."""
+    lines = [line for line in text.splitlines() if not line.startswith("#")]
+    reader = csv.DictReader(lines)
+    if tuple(reader.fieldnames or ()) != COLUMNS:
+        raise DeclarationRefused(f"a prices file has the columns {','.join(COLUMNS)}")
+    fields: dict[str, dict[str, float | str]] = {}
+    vendors: dict[str, str] = {}
+    for number, row in enumerate(reader, start=2):
+        model, unit = row["model"], row["unit"]
+        field = FIELD_OF_UNIT.get(unit)
+        if field is None:
+            raise DeclarationRefused(
+                f"line {number}: {unit!r} is not a unit; one of {', '.join(FIELD_OF_UNIT)}"
+            )
+        if vendors.setdefault(model, row["vendor"]) != row["vendor"]:
+            raise DeclarationRefused(
+                f"line {number}: {model} is {vendors[model]}'s already: a model is priced once"
+            )
+        priced = fields.setdefault(model, {"as_of": ""})
+        if field in priced:
+            raise DeclarationRefused(f"line {number}: {model} {unit} is priced twice")
+        priced[field] = _usd(row["usd"], number)
+        priced["as_of"] = max(str(priced["as_of"]), row["as_of"])
+    return {model: Rate.model_validate(priced) for model, priced in fields.items()}
+
+
+def rates_changed(box: Mapping[str, Rate], written: Mapping[str, Rate]) -> RatesChange:
+    """Each model of the file as new, changed or the same, and what only the box holds."""
+    return RatesChange(
+        added=tuple(sorted(model for model in written if model not in box)),
+        changed=tuple(
+            sorted(model for model in written if model in box and box[model] != written[model])
+        ),
+        unchanged=tuple(sorted(model for model in written if box.get(model) == written[model])),
+        only_on_the_box=tuple(sorted(model for model in box if model not in written)),
+    )
+
+
+# Interruption and end-of-turn models run inside livekit and cost nothing: no row, not unpriced.
+def _priced(used: ModelUsage, rates: Mapping[str, Rate]) -> list[CostRow] | None:
+    rate = rate_of(rates, used.model)
+    match used:
+        case LLMModelUsage():
+            return None if rate is None or rate.input is None else _tokens(used, rate)
+        case TTSModelUsage():
+            per = None if rate is None else rate.characters
+            return _counted(used, "characters", quantity=used.characters_count or 0, per=per)
+        case STTModelUsage():
+            per = None if rate is None else rate.audio_seconds
+            return _counted(used, "audio_seconds", quantity=used.audio_duration or 0.0, per=per)
+        case _:
+            return []
+
+
+# Plugins count cached and cache-written tokens inside input_tokens, so both come off the
+# fresh input before it is priced.
+def _tokens(used: LLMModelUsage, rate: Rate) -> list[CostRow]:
+    cached = used.input_cached_tokens or 0
+    written = used.input_cache_creation_tokens or 0
+    counted: list[tuple[Unit, int, float | None]] = [
+        ("input_tokens", max((used.input_tokens or 0) - cached - written, 0), rate.input),
+        (
+            "cached_input_tokens",
+            cached,
+            rate.input if rate.cached_input is None else rate.cached_input,
+        ),
+        ("cache_creation_tokens", written, rate.cache_creation),
+        ("output_tokens", used.output_tokens or 0, rate.output),
+    ]
+    return [
+        _row(used, unit, quantity=tokens, per=per, usd=tokens / A_MILLION * per)
+        for unit, tokens, per in counted
+        if tokens > 0 and per is not None
+    ]
+
+
+def _counted(
+    used: TTSModelUsage | STTModelUsage,
+    unit: Literal["characters", "audio_seconds"],
+    *,
+    quantity: float,
+    per: float | None,
+) -> list[CostRow] | None:
+    if per is None:
+        return None
+    if quantity <= 0:
+        return []
+    return [_row(used, unit, quantity=quantity, per=per, usd=quantity * per)]
+
+
+# A token row carries its price per million tokens, as a pricing page prints it.
+def _row(
+    used: ModelUsage,
+    unit: Unit | Literal["characters", "audio_seconds"],
+    *,
+    quantity: float,
+    per: float,
+    usd: float,
+) -> CostRow:
+    return CostRow(
+        provider=used.provider,
+        model=used.model,
+        unit=unit,
+        quantity=quantity,
+        unit_price_usd=per,
+        usd=round(usd, 6),
+    )
+
+
+# A carrier prices a leg by the longest prefix of its number, as its own rate tables do; the row
+# names the prefix it matched, never the number.
+def _leg_row(leg: PhoneLeg, rates: Mapping[str, Rate]) -> CostRow | None:
+    key = longest_prefix(rates, f"{_leg_name(leg)}/{leg.number}")
+    per = None if key is None else rates[key].minutes
+    if key is None or per is None:
+        return None
+    minutes = math.ceil(leg.seconds / A_MINUTE_S) if leg.seconds > 0 else 0
+    return CostRow(
+        provider=leg.carrier,
+        model=key,
+        unit="minutes",
+        quantity=minutes,
+        unit_price_usd=per,
+        usd=round(minutes * per, 6),
+    )
+
+
+def _compute_row(seconds: float, rates: Mapping[str, Rate]) -> CostRow | None:
+    rate = rates.get(COMPUTE)
+    if seconds <= 0 or rate is None or rate.minutes is None:
+        return None
+    minutes = round(seconds / A_MINUTE_S, 4)
+    return CostRow(
+        provider=PLATFORM,
+        model=COMPUTE,
+        unit="minutes",
+        quantity=minutes,
+        unit_price_usd=rate.minutes,
+        usd=round(minutes * rate.minutes, 6),
+    )
+
+
+def _leg_name(leg: PhoneLeg) -> str:
+    return f"{leg.carrier}-{leg.direction}"
+
+
+def _usd(text: str, number: int) -> float:
+    try:
+        usd = float(text)
+    except ValueError:
+        raise DeclarationRefused(f"line {number}: {text!r} is not a price in dollars") from None
+    if usd < 0:
+        raise DeclarationRefused(f"line {number}: a price is never below zero")
+    return usd

pinecall/providers/tried.py

@@ -0,0 +1,104 @@
+"""A stage a setting changes, tried once outside a call: a vendor's no is heard where it is set."""
+
+import asyncio
+import contextlib
+from typing import Never
+
+from livekit import rtc
+from livekit.agents import APIConnectionError, APIConnectOptions, APIError, APITimeoutError, stt
+from livekit.agents.llm import ChatContext
+from livekit.agents.utils import http_context
+
+from pinecall.domain.agent import Turn
+from pinecall.domain.errors import DeclarationRefused, UpstreamFailed
+from pinecall.providers import voices
+from pinecall.providers.build import Modality, Running, llm_of, stt_of
+
+# A vendor slower than this to say a word is not refusing the setting, it is not answering.
+TRY_S = 12.0
+
+LINE = "OK."
+
+# Ears that keep listening once the input ends took the connection: a refusal comes back sooner.
+LISTENED_S = 4.0
+
+# Half a second of silence at the rate every plugin takes, to open the ears and close them.
+RATE = 16_000
+
+REFUSED = "{vendor} refused the {stage} this sets: {why}"
+
+UNANSWERED = (
+    "{vendor} did not answer while the {stage} this sets was tried: {why}; nothing was kept, "
+    "try again"
+)
+
+STAGE_NAMES: dict[Modality, str] = {"llm": "model", "stt": "ears", "tts": "voice"}
+
+# Once, at once: a setting is not worth livekit's retries, and a person is waiting on the answer.
+ONCE = APIConnectOptions(max_retry=0, timeout=10.0)
+
+SILENCE = rtc.AudioFrame(
+    data=bytes(RATE), sample_rate=RATE, num_channels=1, samples_per_channel=RATE // 2
+)
+
+
+async def tried(stage: Modality, running: Running, turn: Turn | None = None) -> None:
+    """The stage asked one small thing; the vendor's no refused, its silence UpstreamFailed."""
+    named = STAGE_NAMES[stage]
+    try:
+        # Outside a call there is no job to lend the plugins its HTTP session: it is opened here.
+        async with asyncio.timeout(TRY_S), http_context.open():
+            if stage == "tts":
+                await voices.sample(running, LINE)
+            elif stage == "llm":
+                await _answered(running)
+            else:
+                await _heard(stt_of(running, turn))
+    except TimeoutError as slow:
+        why = f"no answer in {TRY_S:.0f} s"
+        unanswered = UNANSWERED.format(vendor=running.vendor, stage=named, why=why)
+        raise UpstreamFailed(unanswered) from slow
+    except (APIConnectionError, APITimeoutError) as silent:
+        unanswered = UNANSWERED.format(vendor=running.vendor, stage=named, why=silent.message)
+        raise UpstreamFailed(unanswered) from silent
+    except APIError as refused:
+        refusal = REFUSED.format(vendor=running.vendor, stage=named, why=refused.message)
+        raise DeclarationRefused(refusal) from refused
+    except UpstreamFailed as failed:
+        cause = failed.__cause__
+        if isinstance(cause, APIConnectionError | APITimeoutError):
+            raise UpstreamFailed(
+                UNANSWERED.format(vendor=running.vendor, stage=named, why=cause.message)
+            ) from cause
+        raise DeclarationRefused(
+            REFUSED.format(vendor=running.vendor, stage=named, why=str(failed))
+        ) from failed
+
+
+async def _answered(running: Running) -> None:
+    model = llm_of(running)
+    context = ChatContext.empty()
+    context.add_message(role="user", content=LINE)
+    try:
+        async with model.chat(chat_ctx=context, conn_options=ONCE) as stream:
+            async for _ in stream:
+                break
+    finally:
+        await model.aclose()
+
+
+# Ears that only take a whole utterance have nothing to open: they are tried by the first call.
+# The turn's knobs are the call's, so a silence or a bar the vendor does not take is its no here.
+async def _heard(ears: stt.STT[Never]) -> None:
+    try:
+        if not ears.capabilities.streaming:
+            return
+        async with ears.stream(conn_options=ONCE) as stream:
+            stream.push_frame(SILENCE)
+            stream.end_input()
+            with contextlib.suppress(TimeoutError):
+                async with asyncio.timeout(LISTENED_S):
+                    async for _ in stream:
+                        continue
+    finally:
+        await ears.aclose()

pinecall/providers/voices.py

@@ -0,0 +1,174 @@
+"""The voice picker: the voices a vendor lists, and a line spoken by one of them outside a call."""
+
+import dataclasses
+import inspect
+import io
+import time
+import wave
+from collections.abc import AsyncIterator, Mapping
+from dataclasses import dataclass
+
+from livekit.agents import APIError, APIStatusError
+from livekit.agents.tts import SynthesizedAudio
+from livekit.agents.utils import http_context
+
+from pinecall.domain.errors import NotFound, UpstreamFailed
+from pinecall.domain.names import Json, JsonObject
+from pinecall.providers.build import Running, a_list, a_mapping, tts_of
+from pinecall.providers.catalog import Providers
+
+SAMPLE_WIDTH = 2  # 16-bit PCM, as every plugin emits it
+
+# Plugins name a voice's id and name differently; the first a row carries is it.
+_THE_ID = ("id", "voice_id", "voice")
+_THE_NAME = ("name", "voice_name", "display_name")
+
+NOT_LISTED = "{vendor} lists no voices here: its voice is the vendor's own id, set as it is"
+
+
+@dataclass(frozen=True)
+class ListedVoice:
+    """A voice as the picker shows it: its id, its name, and the vendor's row whole."""
+
+    id: str
+    name: str
+    detail: JsonObject
+
+
+@dataclass(frozen=True)
+class Sample:
+    """A line spoken as WAV, with when its first audio came and when it ended."""
+
+    wav: bytes
+    # Includes setting up the connection, which a call already warmed.
+    first_audio_ms: int
+    total_ms: int
+
+
+async def voices(running: Running) -> list[ListedVoice]:
+    """The voices a vendor lists on the stage's key, where its plugin lists any; NotFound if not."""
+    async with http_context.open():
+        speech = tts_of(running)
+        listing = getattr(speech, "list_voices", None)
+        if not callable(listing):
+            raise NotFound(NOT_LISTED.format(vendor=running.vendor))
+        try:
+            params = listing()
+            if not inspect.isawaitable(params):
+                raise NotFound(NOT_LISTED.format(vendor=running.vendor))
+            answered: object = await params
+        except APIError as refused:
+            raise _refused(running.vendor, "did not list its voices", refused) from refused
+        finally:
+            await speech.aclose()
+    return [voice for row in _rows(answered) if (voice := _listed(row)) is not None]
+
+
+def kept(configured: Providers, vendor: str, language: str | None) -> list[ListedVoice]:
+    """The voices the providers row lists for a vendor, in that language or in every one."""
+    found: list[ListedVoice] = []
+    for key, listed in configured.listed.items():
+        named, _, spoken = key.partition("/")
+        if named != vendor or (language is not None and spoken != language):
+            continue
+        for voice in listed:
+            detail: JsonObject = {**voice.model_dump(), "language": spoken}
+            found.append(ListedVoice(id=voice.id, name=voice.name, detail=detail))
+    return found
+
+
+def lists_any(configured: Providers, vendor: str) -> bool:
+    """Whether the providers row lists a voice of this vendor in any language."""
+    return any(key.partition("/")[0] == vendor for key in configured.listed)
+
+
+async def sample(running: Running, line: str) -> Sample:
+    """The line spoken by the stage's voice, built as a call builds it, or the vendor's words."""
+    async with http_context.open():
+        speech = tts_of(running)
+        try:
+            if speech.capabilities.streaming:
+                async with speech.stream() as stream:
+                    stream.push_text(line)
+                    stream.end_input()
+                    return await _heard(stream)
+            async with speech.synthesize(line) as chunks:
+                return await _heard(chunks)
+        except APIError as refused:
+            raise _refused(running.vendor, "did not say it", refused) from refused
+        finally:
+            await speech.aclose()
+
+
+# The vendor's own words, and its status where it answered with one.
+def _refused(vendor: str, what: str, error: APIError) -> UpstreamFailed:
+    status = f" ({error.status_code})" if isinstance(error, APIStatusError) else ""
+    return UpstreamFailed(f"{vendor} {what}{status}: {error.message}")
+
+
+# A listing is a list of rows, each a dataclass or a mapping; one that is a mapping of names
+# is read as rows named by its keys.
+def _rows(answered: object) -> list[JsonObject]:
+    if a_mapping(answered):
+        return [{"id": key, "name": key} for key in answered]
+    return [_row(item) for item in answered] if a_list(answered) else []
+
+
+def _row(item: object) -> JsonObject:
+    if dataclasses.is_dataclass(item) and not isinstance(item, type):
+        return _json(dataclasses.asdict(item))
+    return _json(item) if a_mapping(item) else {}
+
+
+def _json(fields: Mapping[str, object]) -> JsonObject:
+    return {name: _value(value) for name, value in fields.items()}
+
+
+def _value(value: object) -> Json:
+    if isinstance(value, str | int | float | bool) or value is None:
+        return value
+    if a_mapping(value):
+        return _json(value)
+    if a_list(value):
+        return [_value(item) for item in value]
+    return str(value)
+
+
+def _listed(row: JsonObject) -> ListedVoice | None:
+    named = next((str(row[name]) for name in _THE_ID if row.get(name)), None)
+    if named is None:
+        return None
+    shown = next((str(row[name]) for name in _THE_NAME if row.get(name)), named)
+    return ListedVoice(id=named, name=shown, detail=row)
+
+
+# livekit refuses a synthesis that pushed no audio, so what reaches here has some.
+async def _heard(audio: AsyncIterator[SynthesizedAudio]) -> Sample:
+    started = time.perf_counter()
+    first: float | None = None
+    pcm = bytearray()
+    rate, channels = 0, 0
+    async for chunk in audio:
+        first = first or time.perf_counter()
+        pcm += bytes(chunk.frame.data)
+        rate, channels = chunk.frame.sample_rate, chunk.frame.num_channels
+    ended = time.perf_counter()
+    return Sample(
+        wav=_wav(bytes(pcm), rate, channels),
+        first_audio_ms=_ms(started, first or ended),
+        total_ms=_ms(started, ended),
+    )
+
+
+def _wav(pcm: bytes, rate: int, channels: int) -> bytes:
+    out = io.BytesIO()
+    with wave.open(out, "wb") as file:
+        file.setnchannels(channels)
+        file.setsampwidth(SAMPLE_WIDTH)
+        file.setframerate(rate)
+        file.writeframes(pcm)
+    return out.getvalue()
+
+
+def _ms(started: float, at: float) -> int:
+    return round((at - started) * 1000)