feat: bundle GGUF format (ASR, VAD, diarization, sound events and voice in one file)

[localai-org-maint-bot]

What and why

Today a user who wants transcription plus voice activity detection, diarization, sound events and speaker naming passes several GGUF files. This PR adds a bundle GGUF: one file that holds several components. Each component has its own namespaced tensors and keys, and its own licence, source and credit. There is no requantisation: every tensor keeps the type it was published with, so an F16 ASR model can sit next to a Q8_0 diarization model. Plain GGUF files load unchanged. An old reader refuses a bundle cleanly.

Format and rules are in docs/bundle.md.

Components

Kind	What it holds	How it loads
asr	a Parakeet or Nemotron model, with its own VAD head if it has one	the normal loader, through a prefixed view
vad	Silero VAD, or a VAD-only slice from #87	SileroVad or Model::load_vad_only
diar	Nemotron-3-Diarization	DiarizationModel::load(path, component)
ced	a CED sound-event model (ced.cpp)	the unmodified ced.cpp loader, see below
voice	a speaker encoder (voice-detect.cpp)	the unmodified voice-detect.cpp loader, see below

ced.cpp and voice-detect.cpp can only load from a path. For those two kinds the component is copied out as a standalone GGUF (an in-memory file through memfd_create on Linux, an owner-only temporary file that is removed after loading elsewhere; PARAKEET_BUNDLE_NO_MEMFD=1 forces the file) and the path is handed to the unmodified loader. Only that component's bytes are read. A load_from_buffer hook in those two repos would remove the copy; that is a follow-up.

C-API (additive, ABI 10 unchanged)

• parakeet_capi_load_component(path, name): opens asr, vad, diar, ced, voice and VAD-only slice components.
• parakeet_capi_bundle_components_json(path): lists components with kind, licence, source, credit, hashes and sizes.
• parakeet_capi_load_error(): thread-local reason of the last failed load.
• parakeet_capi_load on a bundle opens the only asr component, or lists the names when it is ambiguous.
• A voice component reports its speaker identity as sha256: plus the source_sha256 from the bundle header, so profiles made with the standalone file match.

CLI

• parakeet-cli info <file>: components, licences and sizes (header only).
• transcribe, vad, diarize, enroll: --model bundle.gguf [--component NAME]; transcribe --vad [--vad-component NAME].
• scene: a bundle works for --model, --diar, --sound and --speakers; --asr-component, --diar-component, --sound-component and --speakers-component pick a component when there is more than one of a kind.
• bench, streaming and other subcommands refuse a bundle with a clear message.

scripts/bundle_gguf.py

Builds a bundle from a JSON manifest. Modes: --list, --verify (recomputes every tensor hash and checks keys), --notice (prints the credits and the full licence texts of every component, from scripts/bundle_licenses/). It refuses components under NC or ND licences, with a missing or empty licence, licence URL or credit, with a licence that contradicts the input's own, and known sources with the wrong licence. It refuses the audeering heads and the NVIDIA Open Model License models by source, licence or name. Output is deterministic.

Tests

• test_bundle (model independent): synthetic bundles, header parsing, selection rules, tensor bytes, bytes read per component, malformed and truncated files, the standalone copy for ced and voice in both the memfd and temporary-file paths with nothing left behind, all C-API calls.
• tests/python/check_bundle.py: build, verify and refusal cases, NOTICE texts.
• test_bundle_models and test_bundle_full (label model): a real bundle against its source files: ASR transcript, diarization JSON, CED scores and speaker embedding bitwise, speaker identity, Silero probabilities, named diarization, partial reads, refusal by the unmodified third-party loaders.
• ctest -LE model: 34 of 34. With the model environment, the only failures are test_relpos_attention_local_chunked and test_capi_timestamps (known) and test_combined_offline (45 against 65 streaming words), which fails the same way on a build without the bundle code.

Results on two real bundles (not published)

Bundle	Contents	Size
small	110M Q8_0, Nemotron-3-Diarization Q8_0, CED-small Q8_0, WeSpeaker F32, Silero F16	337,885,152 bytes
standard	tdt-0.6b-v3 Q8_0, the same diarization, CED, WeSpeaker and Silero	1,100,752,640 bytes

For both: --verify against all source files matches tensor for tensor; the transcript, diarization segments, scene output with all four models, named speakers, CED scores, speaker embeddings and enroll registries equal those of the standalone files; two builds of the same manifest are byte-identical. Loading only the Silero component reads 1.7 MB of the 1.1 GB file; loading a CED component reads about twice its size (the copy plus the loader's read).

Limits

• GPU and streaming ASR through a bundle are not verified. Other ASR families, K-quant components, CED-tiny and CED-base were not tried.
• The temporary-file fallback is written for Windows and macOS but was not run there.
• ECAPA tensor names are 61 bytes long, so in a bundle it needs a one-letter component name (the script limit is 63 bytes).
• An old reader refuses a bundle cleanly, but it reads the whole file first.
• No bundle is published or announced. When one is shipped, the full licence texts of every component must ship with it (see "Licences" in docs/bundle.md). The WeSpeaker licence is recorded as CC-BY-4.0, the stricter of two readings; the shipped OpenMDW text was taken from openmdw.ai and needs a check.

Assisted-by: Claude:claude-sonnet-5-5 [Claude Code]

🤖 Generated with Claude Code

[localai-org-maint-bot]

Scope update: this PR now covers the full bundle, not only phase 1. The title and description above describe the first commits.

Components (one bundle GGUF can hold any of them; docs/bundle.md has the format):

• asr: a Parakeet ASR model, with its VAD head if it has one (Ultra, Redux)
• vad: a Silero model, or a VAD-only slice from feat: VAD-only GGUF files (head, front end, subsampler) and a slicer #87 (told apart by parakeet.arch)
• diar: Nemotron diarization, read natively through the same prefixed loader as asr
• ced: ced.cpp sound events
• voice: voice-detect.cpp speaker encoders (WeSpeaker, ECAPA, ERes2Net, CAM++)

ced.cpp and voice-detect.cpp open a model by path only, and their sources are unchanged. A ced or voice component is written as a standalone GGUF (an in-memory file via memfd_create on Linux, else a temporary file removed after the load) and that path is passed to the loader. The output is bitwise equal to the single-model file in the tests. A load_from_buffer hook in those two projects would remove the copy; it is noted in the docs as a follow-up.

C-API (additive, ABI stays 10): parakeet_capi_load_component now opens diar, ced, voice and slice components; parakeet_capi_load still picks the ASR component. CLI: scene takes a bundle for --model, --diar, --sound, --speakers (component by kind, or --asr-component, --diar-component, --sound-component, --speakers-component), enroll --component, diarize takes a bundle, info describes every kind.

Licences: each component carries its own licence, credit and changes. scripts/bundle_gguf.py checks known sources against agreed licences (Nemotron diarization OpenMDW-1.1, CED, ECAPA and ERes2Net Apache-2.0, WeSpeaker CC-BY-4.0, Silero MIT), refuses the audeering heads and the EOU model, and --notice prints the credits plus the full licence texts to ship.

Tests: test_bundle (synthetic, includes the standalone copy through memfd and the temporary-file path), check_bundle.py (kinds, refusals, NOTICE), and the model tests test_bundle_models and test_bundle_full (a real bundle equals the single-model files: transcript, diarization JSON, CED scores, speaker embedding, Silero probabilities).