Migrating the GLaDOS Stack

# labs/platform_config.py
from pathlib import Path

TEGRA_RELEASE = Path("/etc/nv_tegra_release")
DEVICE_TREE_MODEL = Path("/proc/device-tree/model")


def detect_platform() -> str:
    """Name this board from the fingerprints its firmware and installer left."""
    if TEGRA_RELEASE.exists():
        return "jetson"
    try:
        model = DEVICE_TREE_MODEL.read_text(errors="replace").lower()
    except OSError:
        return "unknown"
    return "rpi" if "raspberry pi" in model else "unknown"


if __name__ == "__main__":
    print(f"platform: {detect_platform()}")

$ uv run python -m labs.platform_config   # run on all three machines
platform: jetson
platform: rpi
platform: unknown

There is no portable way to ask Python what board it is running on. The platform module reports the kernel and the processor architecture, and both of these boards answer aarch64 Linux to that question, so it cannot tell them apart. What can tell them apart is the disk. The JetPack installer writes /etc/nv_tegra_release, the file chapter 76 parsed for a release version; here its mere existence is the whole answer, and no parsing is needed. Raspberry Pi firmware writes the board's marketing name into the device tree, where the kernel exposes it as a file. Neither marker moves between reboots, and neither can be present on the wrong board.

Two small defensive choices. The device-tree file is read inside a try instead of behind an exists() test, because a file that exists and cannot be read leads to the same conclusion as a file that is absent, and one code path is easier to trust than two. And errors="replace" is there because device-tree strings are NUL-terminated: the bytes on that file end with a zero byte that is not valid text in every decoder, and a diagnostic function should never be the thing that crashes. Anything unrecognised comes back as "unknown", which is the correct name for a laptop and a key the table in the next section really declares.

# labs/platform_config.py — continued
import json

HARDWARE_PATH = Path("configs/hardware.json")


def load_json_safe(path: Path) -> dict:
    """The file as a dict, or an empty one, with a line saying which happened."""
    try:
        return json.loads(path.read_text())
    except (OSError, json.JSONDecodeError) as exc:
        print(f"[config] ignoring {path}: {type(exc).__name__}")
        return {}


if __name__ == "__main__":
    print(f"platform: {detect_platform()}")
    print(f"on disk:  {load_json_safe(HARDWARE_PATH)}")

$ uv run python -m labs.platform_config   # on the Jetson, before any config has been copied over
[config] ignoring configs/hardware.json: FileNotFoundError
platform: jetson
on disk:  {}

An empty dict is a working answer here, and that is a deliberate design decision rather than laziness about error handling. A board being set up for the first time has no hardware.json, and a hand-edited one can carry a trailing comma. If either case raises, the script dies before it has told you the one thing you most wanted to know, which is what board it thinks it is on; you then spend ten minutes debugging a comma while believing you are debugging a migration. Degrading to an empty overlay costs nothing, because the layer underneath is chapter 31's registry of defaults and the layer above is the platform table.

The printed line is what keeps degradation honest. Silence would mean a missing file and a present file produce identical output, and the day someone puts hardware.json in the wrong directory you would have no way to see it. One line, on the way past, and the difference is visible.

# labs/platform_config.py — continued
PLATFORM_OVERRIDES: dict[str, dict[str, dict]] = {
    "jetson": {
        "stt":  {"device": "cuda", "compute_type": "float16"},
        "tts":  {"device": "cuda"},
        "llm":  {"model_storage": "/mnt/nvme/ollama/models"},
        "gpio": {"library": "Jetson.GPIO"},
    },
    "rpi": {
        "stt":  {"device": "cpu", "compute_type": "int8"},
        "tts":  {"device": "cpu"},
        "llm":  {"model_storage": "/home/pi/.ollama/models"},
        "gpio": {"library": "RPi.GPIO"},
    },
    "unknown": {
        "stt":  {"device": "cpu", "compute_type": "int8"},
        "tts":  {"device": "cpu"},
        "llm":  {"model_storage": str(Path.home() / ".ollama" / "models")},
        "gpio": {"library": "none"},
    },
}

Read that table as the settings this resolver proposes for each board. It does not install drivers, relocate Ollama's storage or replace every earlier composition root. The keys are the component names chapter 31's registry already uses, so a row here lands in exactly one component's settings and nowhere else.

The "unknown" entry is a real board, not a fallback nobody meant. A laptop gets CPU inference, a model directory under the home directory, and a GPIO library named "none". That GPIO row records intended configuration; chapter 81's guarded import does its own detection and does not consume this row. The entry lets the resolver be written, run and argued with on the machine you are sitting at, days before you ever SSH into the Jetson.

# labs/platform_config.py — continued
from labs.system_config import ComponentConfig, SystemConfig, build_default_config


def build_board_config() -> SystemConfig:
    """Chapter 31's registry, plus the one component the body needs."""
    cfg = build_default_config()
    cfg.add_component(ComponentConfig("gpio", True, {"library": "none"}))
    return cfg


def resolve(platform: str, on_disk: dict) -> SystemConfig:
    """Defaults, then the operator's file, then the board. The board wins."""
    overrides = PLATFORM_OVERRIDES[platform]
    resolved = SystemConfig()
    for comp in build_board_config().components:
        settings = {**comp.settings,
                    **on_disk.get(comp.name, {}),
                    **overrides.get(comp.name, {})}
        resolved.add_component(ComponentConfig(comp.name, comp.enabled, settings))
    return resolved


def print_resolved(platform: str, cfg: SystemConfig) -> None:
    width = max(len(c.name) for c in cfg.components)
    print(f"platform: {platform}")
    for comp in cfg.components:
        print(f"  {comp.name:<{width}}  {json.dumps(comp.settings)}")


def main() -> None:
    platform = detect_platform()
    print_resolved(platform, resolve(platform, load_json_safe(HARDWARE_PATH)))


if __name__ == "__main__":
    main()

$ uv run python -m labs.platform_config | grep -E 'platform|stt|tts|memory|llm|gpio'   # on the Jetson, still no hardware.json
[config] ignoring configs/hardware.json: FileNotFoundError
platform: jetson
  stt            {"model": "base", "device": "cuda", "compute_type": "float16", "sample_rate": 16000}
  tts            {"voice": "en_US-lessac-medium", "sample_rate": 22050, "device": "cuda"}
  memory         {"db_path": "glados/data/memory.db"}
  llm            {"model": "llama3.2:3b", "host": "http://localhost:11434", "model_storage": "/mnt/nvme/ollama/models"}
  gpio           {"library": "Jetson.GPIO"}

$ uv run python -m labs.platform_config | grep -E 'platform|stt|tts|memory|llm|gpio'   # the same command, same tree, on the laptop
[config] ignoring configs/hardware.json: FileNotFoundError
platform: unknown
  stt            {"model": "base", "device": "cpu", "compute_type": "int8", "sample_rate": 16000}
  tts            {"voice": "en_US-lessac-medium", "sample_rate": 22050, "device": "cpu"}
  memory         {"db_path": "glados/data/memory.db"}
  llm            {"model": "llama3.2:3b", "host": "http://localhost:11434", "model_storage": "/home/dev/.ollama/models"}
  gpio           {"library": "none"}

The registry holds thirteen components and print_resolved prints all of them, so the pipe through grep is there to put the rows this chapter is arguing about next to each other; drop it and you get the whole config. Two boards, one tree, one command, and rows that show the proposed settings. The changed values are visible and the values that did not change are visible too: the model name, the Ollama host and the database path are identical in both transcripts. Neither run constructed a speech engine. Notice the key order in the tts line, where device appears at the end. A dict spread keeps the position of a key it overwrites and appends a key it introduces, so the tail of each line is the part the platform table added.

resolve builds a fresh SystemConfig and never writes into the one build_board_config returned. Nothing forces that here, since the factory hands out new dicts on every call, but the habit is what makes the function safe to call twice in one process with two different platform names, which is exactly what one of the exercises does.

# labs/platform_config.py — continued
RESOLVED_PATH = Path("glados/data/resolved_hardware.json")


def save_resolved(cfg: SystemConfig, path: Path) -> Path:
    """Record resolved settings for diagnosis, without claiming a consumer loaded them."""
    path.parent.mkdir(parents=True, exist_ok=True)
    body = {c.name: c.settings for c in cfg.components if c.enabled}
    path.write_text(json.dumps(body, indent=2) + "\n")
    return path


def main() -> None:
    platform = detect_platform()
    cfg = resolve(platform, load_json_safe(HARDWARE_PATH))
    print_resolved(platform, cfg)
    print(f"recorded at {save_resolved(cfg, RESOLVED_PATH)}")

$ uv run python -m labs.platform_config   # on the Jetson, unfiltered this time
platform: jetson
  audio_capture  {"sample_rate": 16000, "channels": 1, "chunk": 1024}
  stt            {"model": "base", "device": "cuda", "compute_type": "float16", "sample_rate": 16000}
  wake_word      {"phrase": "glados", "threshold": 0.6}
  tts            {"voice": "en_US-lessac-medium", "sample_rate": 22050, "device": "cuda"}
  memory         {"db_path": "glados/data/memory.db"}
  context        {"turns": 6, "facts": 4}
  llm            {"model": "llama3.2:3b", "host": "http://localhost:11434", "model_storage": "/mnt/nvme/ollama/models"}
  safety         {"policy": "configs/safety.json"}
  drivers        {"port": "/dev/ttyUSB0", "baud": 115200}
  automation     {"rules": "configs/automation.json"}
  scheduler      {"tick_seconds": 30}
  voice_loop     {"max_turns": 0}
  gpio           {"library": "Jetson.GPIO"}
recorded at glados/data/resolved_hardware.json

Chapter 34 saved the voice loop's settings for the same reason: three days after a strange session, memory offers several plausible accounts of what was configured and a file offers one. The distinction that matters is which file. Nothing loads resolved_hardware.json at startup, because loading it would put a stale copy of the answer ahead of the live detection and reintroduce the bug the next section is about. It is a record, written for you, and it is the right thing to paste into a bug report. Record the actual engine/provider alongside it; a desired device and an observed device answer different questions.

Now connect the resolver to the voice composition root. Add this function to labs/platform_config.py; call it instead of build_core(build_default_config()) when assembling the board's voice loop. The plain python -m labs.platform_config command above still only prints and saves settings, so it remains usable without model downloads.

from glados.core import GladOSCore


def build_board_core() -> GladOSCore:
    """Resolve once at this composition root, validate, then construct the voice providers."""
    platform = detect_platform()
    cfg = resolve(platform, load_json_safe(HARDWARE_PATH))
    errors = validate_platform(platform, cfg)
    if errors:
        raise ValueError("; ".join(errors))
    save_resolved(cfg, RESOLVED_PATH)
    from labs.wire_providers import build_core

    return build_core(cfg)

validate_platform is defined in the next section; finish the file before calling this function. The resulting core accepts the same run_turn call as chapter 32. Chapter 44's WhisperSTT passes both device and compute_type to WhisperModel. Its F5 provider passes tts.device to F5TTS when tts.engine is f5. The default Piper provider does not use that device row and remains a separate CPU voice path. The older chapter 32 composition root also reads the Whisper compute type and F5 device from settings.

This wiring covers those speech providers only. Ollama runs in its own service; changing llm.model_storage here does not set that service's OLLAMA_MODELS environment. GPIO selection and the older standalone wake-word/transcription scripts keep their own startup paths. Inspect the entry point your service actually runs before calling the migration complete, then check the installed backend and measure a real turn. A merge validator cannot do that measurement for you.