jrich-wakeword-trainer/deploy/wakeword-training/README.md

Wakeword Training Image

This directory packages the one-shot, GPU-only image used by both the offline operator runner and downloadable local trainer. It is not part of compose.yaml, exposes no port, and contains no gateway credentials or listener dependencies.

The image uses LiveKit WakeWord 0.2.1, source revision 1ec7f680df30ff4ca0ebae6b5983441e94b10980, and source-distribution SHA-256 cf2d9cf4867812c06788f64c15e49abd909d9d6291f0a13f1c3f9cb649fa6127.

The gateway's .env deliberately contains only WAKEWORD_CATALOG_* settings. Do not add runner GPU, image, work-root, timeout, or retention values to it: the host-only runner receives those as explicit invocation inputs and refuses to run without --enable. This directory is neither a Compose service nor normal CI input.

Before an operator builds it, run:

scripts/build-wakeword-training-image \
  registry.example/jr-wakeword-training:0.2.1

The command builds from the reviewed, complete requirements.wheelhouse.lock with SHA-256 hashes; it never rewrites that lock. Refresh the lock only in a separate reviewed dependency-update change, then commit it before building a release image. It becomes part of each run's provenance. The pinned base image is in base-image.lock.json; the image build may install the reviewed dependencies, but a training container runs with --network none. Do not run this setup during normal gateway CI.

The runtime is designed for --network none, a read-only /inputs bind mount, a writable /run bind mount, a read-only container root, and no Linux capabilities. A commercial run validates sources.lock.json, rejects default ACAV, unknown-license RIR mirrors, and unapproved Piper/VoxCPM outputs, copies only hash-locked files into /run, then invokes the released CLI's augment, train, export, and eval stages. It never calls livekit-wakeword setup or generate in the commercial lane.

For compatibility with the released CLI only, source-lock-approved general-negative feature bundles are copied to its fixed ACAV/validation filenames beneath the isolated staging directory. The recorded source lock and materialization manifest retain their real source IDs and hashes; no ACAV data is admitted or downloaded.

quarantined_smoke is a separately named wrapper and stays permanently non-promotable. It may exercise the upstream run command only after its operator has separately prepared test data; network isolation still prevents an implicit setup/download in the run container.

local_experiment is the downloadable-trainer lane. A separate, explicit setup container may populate the user's versioned LiveKit cache with normal network access. The training container then runs the released generate, augment, train, export, and eval stages with --network none. It produces a local result, never publish-candidate.json. See docs/wakeword-trainer.md.

The source-lock format is documented by source-lock.schema.json; runtime validation additionally verifies every source/terms hash, publisher, version, revision, attribution, commercial disposition, approver, and partition. Raw inputs and features remain in /run evidence only and are never serving artifacts.