Provider contracts

# glados/providers.py
from abc import ABC, abstractmethod


class STTProvider(ABC):
    @abstractmethod
    def transcribe(self, audio_path: str, language: str = "en") -> str:
        """Return the words spoken in the audio file at audio_path."""


if __name__ == "__main__":
    class FakeSTT(STTProvider):
        def transcribe(self, audio_path: str, language: str = "en") -> str:
            return "Are you still pretending to be helpful?"

    print("STTProvider needs:", STTProvider.__abstractmethods__)
    print("FakeSTT needs:    ", FakeSTT.__abstractmethods__)
    print(FakeSTT().transcribe("glados/data/heard.wav"))
    try:
        STTProvider()
    except TypeError as exc:
        print(f"TypeError: {exc}")

$ uv run python -m glados.providers
STTProvider needs: frozenset({'transcribe'})
FakeSTT needs:     frozenset()
Are you still pretending to be helpful?
TypeError: Can't instantiate abstract class STTProvider with abstract method transcribe

The two frozenset lines are the whole mechanism, printed. @abstractmethod records a name on the class; a subclass that overrides the name drops it from the set; a class whose set is still occupied cannot be turned into an object. Note the body of transcribe: a docstring is a legal function body, so no pass and no ellipsis is needed, and that sentence carries what the signature cannot say, which is what the argument means and what the return value is supposed to contain. FakeSTT answers with a fixed line and loads nothing, so the contract's first proof is that something cheap can meet it.

# glados/providers.py — the three contracts
class LLMProvider(ABC):
    @abstractmethod
    def chat(self, text: str, history: list[dict]) -> str:
        """Return her reply to text, given the conversation so far."""


class TTSProvider(ABC):
    @property
    @abstractmethod
    def sample_rate(self) -> int:
        """The rate, in hertz, of the audio this engine writes."""

    @abstractmethod
    def synthesize(self, text: str, output_path: str) -> None:
        """Write spoken audio for text to output_path."""


# glados/fakes.py
from glados.providers import LLMProvider, STTProvider, TTSProvider


class FakeSTT(STTProvider):
    def transcribe(self, audio_path: str, language: str = "en") -> str:
        return "Are you still pretending to be helpful?"


class FakeLLM(LLMProvider):
    def chat(self, text: str, history: list[dict]) -> str:
        return f"I never pretended. ({len(history)} messages remembered)"


class FakeTTS(TTSProvider):
    sample_rate = 22050

    def synthesize(self, text: str, output_path: str) -> None:
        print(f"[TTS {self.sample_rate} Hz] {text[:30]}... -> {output_path}")

$ uv run python -m labs.fake_stack
TTSProvider needs: ['sample_rate', 'synthesize']
FakeTTS needs:     []
rate: 22050 Hz
[TTS 22050 Hz] I never pretended. (0 messages... -> glados/data/glados_says.wav

TTSProvider is the case an alias could not carry: two obligations, and one of them is a value, not a call. Stacking @property under @abstractmethod puts sample_rate in the same required set as synthesize, and FakeTTS satisfies it with a plain class attribute, because the check asks whether an attribute of that name exists and is no longer marked abstract, never whether it is a property. Callers write tts.sample_rate either way, so a fake can answer with a constant while a real engine computes the number from the model it loaded. The demo prints the required names through sorted(), since a set of strings has no order you can rely on between runs. And 22,050 is the number chapter 3 read off a Piper chunk. She listens at 16 kHz and speaks at 22,050 Hz, and the rate is now a question you can ask the object instead of a fact the playback code has to remember.

# labs/wire_providers.py
from glados.core import GladOSCore
from glados.fakes import FakeLLM, FakeSTT, FakeTTS
from glados.providers import LLMProvider, STTProvider, TTSProvider

AUDIO_OUT = "glados/data/glados_says.wav"


def compose(stt: STTProvider, llm: LLMProvider, tts: TTSProvider) -> GladOSCore:
    def speak(text: str) -> None:
        tts.synthesize(text, AUDIO_OUT)

    return GladOSCore(stt=stt.transcribe, llm=llm.chat, tts=speak)


if __name__ == "__main__":
    core = compose(FakeSTT(), FakeLLM(), FakeTTS())
    core.run_turn("glados/data/heard.wav")
    core.run_turn("glados/data/heard.wav")
    print(f"history holds {len(core.history)} messages")

$ uv run python -m labs.wire_providers
You: Are you still pretending to be helpful?
GLaDOS: I never pretended. (0 messages remembered)
[TTS 22050 Hz] I never pretended. (0 messages... -> glados/data/glados_says.wav
You: Are you still pretending to be helpful?
GLaDOS: I never pretended. (2 messages remembered)
[TTS 22050 Hz] I never pretended. (2 messages... -> glados/data/glados_says.wav
history holds 4 messages

Two full turns ran, and glados/core.py was not edited to allow it. stt.transcribe is a bound method: the instance is already attached, so what compose hands over is a callable taking one string and returning one string, which is what the core's alias asked for. llm.chat lines up the same way. The voice is the one that needs an adapter, because the core tells its speaker some text and nothing else, while synthesize also wants a destination; the closure supplies the path and the provider keeps the ability to write anywhere, which the tests that read a file back are going to want. The startup probes from chapter 33 go on working untouched for the same reason, since what they probe is still three callables on the core.

# labs/wire_providers.py — full file
import json
import wave
from pathlib import Path

import ollama
from f5_tts.api import F5TTS
from faster_whisper import WhisperModel
from piper.voice import PiperVoice

from glados.core import GladOSCore
from glados.providers import LLMProvider, STTProvider, TTSProvider
from labs.system_config import SystemConfig, build_default_config

AUDIO_OUT = "glados/data/glados_says.wav"
from labs.glados_voice import REF_FILE, REF_TEXT


class WhisperSTT(STTProvider):
    def __init__(self, model: str, device: str, compute_type: str) -> None:
        self.engine = WhisperModel(model, device=device, compute_type=compute_type)

    def transcribe(self, audio_path: str, language: str = "en") -> str:
        segments, _ = self.engine.transcribe(audio_path, language=language)
        return " ".join(s.text.strip() for s in segments)


class OllamaLLM(LLMProvider):
    def __init__(self, model: str, system_prompt: str) -> None:
        self.model = model
        self.system_prompt = system_prompt

    def chat(self, text: str, history: list[dict]) -> str:
        messages = [{"role": "system", "content": self.system_prompt}]
        messages += history + [{"role": "user", "content": text}]
        return ollama.chat(model=self.model, messages=messages)["message"]["content"]


class PiperTTS(TTSProvider):
    def __init__(self, voice_model: str) -> None:
        self.voice = PiperVoice.load(Path(voice_model))

    @property
    def sample_rate(self) -> int:
        return self.voice.config.sample_rate

    def synthesize(self, text: str, output_path: str) -> None:
        chunks = list(self.voice.synthesize(text))
        with wave.open(output_path, "wb") as out:
            out.setnchannels(chunks[0].sample_channels)
            out.setsampwidth(chunks[0].sample_width)
            out.setframerate(chunks[0].sample_rate)
            out.writeframes(b"".join(c.audio_int16_bytes for c in chunks))


class F5TTSProvider(TTSProvider):
    sample_rate = 24000

    def __init__(self, ref_file: str, ref_text: str, device: str | None = None) -> None:
        self.engine = F5TTS(device=device)
        self.ref_file = ref_file
        self.ref_text = ref_text

    def synthesize(self, text: str, output_path: str) -> None:
        self.engine.infer(ref_file=self.ref_file, ref_text=self.ref_text,
                          gen_text=text, file_wave=output_path, remove_silence=True)


def build_tts(settings: dict) -> TTSProvider:
    if settings.get("engine", "piper") == "f5":
        return F5TTSProvider(REF_FILE, REF_TEXT, device=settings.get("device"))
    return PiperTTS(f"configs/{settings['voice']}.onnx")


def build_core(config: SystemConfig) -> GladOSCore:
    stt_cfg = config.get_component("stt").settings
    llm_cfg = config.get_component("llm").settings
    tts_cfg = config.get_component("tts").settings
    persona = json.loads(Path("configs/personality.json").read_text())

    stt = WhisperSTT(stt_cfg["model"], stt_cfg["device"], stt_cfg["compute_type"])
    llm = OllamaLLM(llm_cfg["model"], persona["system_prompt"])
    tts = build_tts(tts_cfg)
    print(f"voice: {type(tts).__name__} writing {tts.sample_rate} Hz audio")

    def speak(text: str) -> None:
        tts.synthesize(text, AUDIO_OUT)

    return GladOSCore(stt=stt.transcribe, llm=llm.chat, tts=speak)


if __name__ == "__main__":
    build_core(build_default_config()).run_turn("glados/data/heard.wav")

$ uv run python -m labs.wire_providers
voice: PiperTTS writing 22050 Hz audio
You: Are you still pretending to be helpful?
GLaDOS: I have never pretended. You simply assumed.

$ uv run python -m labs.wire_providers   # after "engine": "f5" in configs/system_config.json
voice: F5TTSProvider writing 24000 Hz audio
You: Are you still pretending to be helpful?
GLaDOS: Pretending would require effort. This is just my voice.

Those two runs were captured on the bench, and yours will read differently: the model writes a new reply every time, and your transcript depends on what you said into the microphone. What does not vary is the first line of each run. One JSON edit moved her from a fast local voice to her cloned one, and the only Python that noticed was build_tts. Look closely at what is not interchangeable there: the constructors. PiperTTS wants a path to an .onnx voice while F5TTSProvider wants a reference clip and its transcript, so the two classes are substitutable at every call site and at none of the construction sites. That is exactly why a branch on the engine name lives in one small function, above the line where both results become a TTSProvider and the difference stops mattering. The "engine" key is a new setting on the tts component in the registry from chapter 31, which is the payoff that registry was built for.