Maintaining Loaders and Model-Spec Packages

July 31, 2026 · View on GitHub

For release model downloads, model_specs/*.json is the source of truth and tools/model_manager_v2.py is the only supported manager path.

Integrators treat two surfaces as authoritative:

  1. Runtime loaders — audiocpp_cli --list-loaders --json
  2. Install packages — python3 tools/model_manager_v2.py list --json

Those surfaces must stay in sync. A package that is installable from model_specs/*.json but whose family is missing from --list-loaders looks available to users and then fails at runtime or in search/install UIs.

The Rule

For every installable release package:

FieldMust match
model_specs/<family>.json familyThe family id emitted by the runtime loader registry
model_specs/<family>.json packages[]Ready-to-use GGUF package entries installable by model_manager_v2.py
CMakeLists.txt LOADERS entrymake_<family>_loader or the family's actual factory name so the generated registry includes it
README supported-model tableLists the released family and its tested runtime format

New release packages should be standalone GGUF downloads. If a model is not available as a ready-to-run GGUF package, keep it out of the release download surface until that package exists.

Adding A Model Family

  1. Implement the family under src/models/<family>/ or src/community_models/<family>/.
  2. Register it in CMakeLists.txt with audiocpp_add_model(... INCLUDES ... LOADERS ...).
  3. Add or update model_specs/<family>.json with the release metadata, normalized runtime options, sources, and GGUF packages[].
  4. Make one GGUF package the default package unless there is a specific reason to require users to choose a variant.
  5. Update the model guide and README supported-model table.
  6. Check the install and runtime surfaces:
python3 tools/model_manager_v2.py list --json
python3 tools/model_manager_v2.py info <family-or-package-id>
build/debug/bin/audiocpp_cli --list-loaders --json

Confirm the family appears in both the loader list and the v2 package list.

Parking Or Removing A Family

If a loader is not ready for the release tree:

  1. Do not include it in an enabled audiocpp_add_model(... LOADERS ...) entry.
  2. Do not publish it as a default installable package in model_specs/*.json.
  3. Update README and model docs so the family is not advertised as released.

Do not leave a visible GGUF package entry for a family that is not emitted into the runtime registry.

Family Id Consistency

Pick one runtime family id and keep it consistent across the surfaces that users and tooling match:

  • IVoiceModelLoader::family(), which is what --list-loaders emits
  • model_specs/<family>.json family
  • CMakeLists.txt LOADERS entry
  • README supported-model family column

The factory name in CMake is a registration symbol, not the family id itself. Use make_<family>_loader() when practical because it is easier to audit, but the runtime contract comes from loader->family() matching the spec family. Integrators match on that family string; aliases are not implied.