Skip to content

loader_and_catalog.md

Latest commit

 

History

History
80 lines (60 loc) · 3.32 KB

loader_and_catalog.md

File metadata and controls

80 lines (60 loc) · 3.32 KB
Raw

Maintaining Loaders and Model-Spec Packages

For release model downloads, model_specs/*.json is the source of truth and both tools/model_manager_v2.py and the optional native audiocpp_model_manager consume that package catalog.

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 and, when native model management is enabled, audiocpp_model_manager list

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:

Field Must match
model_specs/<family>.json family The family id emitted by the runtime loader registry
model_specs/<family>.json packages[] Ready-to-use GGUF package entries installable by the Python and native model managers
CMakeLists.txt LOADERS entry make_<family>_loader or the family's actual factory name so the generated registry includes it
README supported-model table Lists 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>
audiocpp_model_manager list
audiocpp_model_manager 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.