Add standalone GGUF support for Hviske v5.3 and Citrinet-256 (0xShug0#46)

* Add standalone GGUF support for Hviske and Citrinet

Define package specs for Hviske v5.3 and Citrinet-256 so the framework resolves native safetensors, standalone GGUF weights, and named config, tokenizer, and vocabulary resources. Decode incompatible quantized convolution reshapes to F32, add native/GGUF regression coverage, document Q8_0 conversion, and record the tested GGUF status.

* Add native q8 reshape preservation test

---------

Co-authored-by: 0xShug0 <231717474+0xShug0@users.noreply.github.com>

Author: mirek190

CMakeLists.txt

@@ -822,6 +822,17 @@ if (ENGINE_BUILD_TESTS)
         COMMAND scaled_dot_product_attention_test
     )
 
+    add_engine_unittest(asr_standalone_gguf_test tests/unittests/test_asr_standalone_gguf.cpp)
+    target_include_directories(asr_standalone_gguf_test PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/tests/unittests)
+    target_compile_definitions(asr_standalone_gguf_test PRIVATE
+        ENGINE_TEST_ASSET_ROOT="${ENGINE_UNITTEST_ASSET_ROOT}"
+    )
+
+    add_test(
+        NAME asr_standalone_gguf_test
+        COMMAND asr_standalone_gguf_test
+    )
+
     add_executable(server_multipart_test
         tests/unittests/test_server_multipart.cpp
         app/server/multipart.cpp

README.md

@@ -706,11 +706,12 @@ The framework also has a reusable GGUF tensor source and a streaming converter.
 container reader is shared by all model families; a family still has to list a `.gguf`
 checkpoint as one of its accepted assets because model configuration and tensor naming
 remain architecture-specific. Qwen3 ASR, Qwen3 Forced Aligner, Qwen3 TTS, Nemotron
-3.5 ASR, VibeVoice-ASR, and Higgs Audio STT currently accept `model.gguf` (including
-`speech_tokenizer/model.gguf` for TTS). The converter recursively embeds sidecar files
+3.5 ASR, VibeVoice-ASR, Higgs Audio STT, Hviske ASR, and Citrinet ASR currently accept
+`model.gguf` (including `speech_tokenizer/model.gguf` for TTS). The converter recursively embeds sidecar files
 up to 64 MiB by default using binary-safe metadata, including nested tokenizer models,
-and Qwen3 ASR, Nemotron ASR, VibeVoice-ASR, and Higgs Audio STT can load the resulting
-`model.gguf` as a standalone file. Pass `--no-sidecars` when a tensor-only container is desired. A
+and Qwen3 ASR, Nemotron ASR, VibeVoice-ASR, Higgs Audio STT, Hviske ASR, and Citrinet
+ASR can load the resulting `model.gguf` as a standalone file. Pass `--no-sidecars` when a
+tensor-only container is desired. A
 `model.safetensors.index.json` is also a first-class tensor source and is merged from
 its routed shards while converting. Exact original tensor ranks are stored separately
 because GGML normally collapses trailing singleton dimensions. Rank-0 safetensors

docs/asr.md

@@ -27,6 +27,15 @@ Citrinet is an offline CTC ASR model. It produces transcription text from speech
 audiocpp_cli --task asr --family citrinet_asr --model models/citrinet --backend cuda --audio speech_16k.wav
 ```
 
+Create a standalone Q8_0 GGUF from the converted Citrinet safetensors layout:
+
+```powershell
+audiocpp_gguf.exe --input models\citrinet\citrinet_256.safetensors --root models\citrinet --output models\citrinet-Q8_0\model.gguf --type q8_0
+```
+
+The GGUF embeds `citrinet_256_config.json` and the vocabulary/tokenizer sidecars, so the
+completed `model.gguf` can be moved, renamed, and passed directly to `--model`.
+
 | Option | Values | Default | Meaning |
 |---|---|---:|---|
 | `--audio` | WAV path | required | Speech input. Use 16 kHz WAV for the example path. |
@@ -100,6 +109,15 @@ Hviske ASR is an offline Cohere ASR model path. The integration exposes Danish p
 audiocpp_cli --task asr --family hviske_asr --model models/hviske-v5.3 --backend cuda --audio speech_16k.wav --text-out transcript.txt
 ```
 
+Create a standalone Q8_0 GGUF:
+
+```powershell
+audiocpp_gguf.exe --input models\hviske-v5.3\model.safetensors --root models\hviske-v5.3 --output models\hviske-v5.3-Q8_0\model.gguf --type q8_0
+```
+
+Configuration, generation settings, and the SentencePiece tokenizer are embedded. The
+completed GGUF can therefore be moved, renamed, and passed directly to `--model`.
+
 | Option | Values | Default | Meaning |
 |---|---|---:|---|
 | `--audio` | WAV path | required | Speech input. |

docs/gguf.md

@@ -139,11 +139,11 @@ Status labels:
 |---|---|---|---|---|---|
 | `ace_step` | No | --- | --- | --- | --- |
 | `chatterbox` | No | --- | --- | --- | --- |
-| `citrinet_asr` | No | --- | --- | --- | --- |
+| `citrinet_asr` | Done | Pass | --- | --- | Pass |
 | `heartmula` | No | --- | --- | --- | --- |
 | `higgs_audio_stt` | Done | Pass | Pass | --- | Pass |
 | `htdemucs` | No | --- | --- | --- | --- |
-| `hviske_asr` | No | --- | --- | --- | --- |
+| `hviske_asr` | Done | Pass | --- | --- | Pass |
 | `index_tts2` | Done | Pass | Pass (drift) | Pass | No (similarity drift, frame drift, text minor drift) |
 | `irodori_tts` | Done | Pass | Pass | --- | Pass (drift) |
 | `marblenet_vad` | No | --- | --- | --- | --- |

include/engine/framework/core/backend_weight_store.h

@@ -244,9 +244,10 @@ class BackendWeightStore {
         if (!ggml_is_quantized(type)) {
             return resolved_type;
         }
-        if (storage_type == assets::TensorStorageType::Native) {
-            return resolved_type;
-        }
+        // A GGUF may store a source matrix in quantized form even when a model
+        // reshapes it into a convolution kernel. Quantized GGML rows cannot end
+        // in a non-block-sized dimension (for example a 1-wide Conv1D kernel),
+        // so decode such native tensors to F32 for the reshaped backend weight.
         if (shape.rank < 2 || shape.last_dim() % ggml_blck_size(type) != 0) {
             return assets::TensorStorageType::F32;
         }

include/engine/models/citrinet_asr/assets.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "engine/framework/assets/tensor_source.h"
+#include "engine/framework/assets/resource_bundle.h"
 
 #include <cstdint>
 #include <filesystem>
@@ -100,14 +100,6 @@ struct CitrinetWeights {
     std::vector<std::string> vocab;
 };
 
-struct CitrinetAssetPaths {
-    std::filesystem::path model_root;
-    std::filesystem::path checkpoint_path;
-    std::filesystem::path config_path;
-    std::filesystem::path vocab_path;
-};
-
-CitrinetAssetPaths resolve_citrinet_assets(const std::filesystem::path & checkpoint_path);
-std::shared_ptr<const CitrinetWeights> load_citrinet_weights_cached(const std::filesystem::path & checkpoint_path);
+std::shared_ptr<const CitrinetWeights> load_citrinet_weights_cached(const std::filesystem::path & model_path);
 
 }  // namespace engine::models::citrinet_asr

include/engine/models/hviske_asr/assets.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "engine/framework/assets/tensor_source.h"
+#include "engine/framework/assets/resource_bundle.h"
 #include "engine/framework/tokenizers/sentencepiece.h"
 
 #include <cstdint>
@@ -63,13 +63,13 @@ struct HviskeConfig {
 };
 
 struct HviskeAssets {
-    std::filesystem::path model_root;
+    engine::assets::ResourceBundle resources;
     HviskeConfig config;
     std::vector<engine::tokenizers::SentencePiecePiece> tokenizer_pieces;
     std::shared_ptr<const engine::assets::TensorSource> model_weights;
 };
 
-std::shared_ptr<const HviskeAssets> load_hviske_assets(const std::filesystem::path & model_root);
+std::shared_ptr<const HviskeAssets> load_hviske_assets(const std::filesystem::path & model_path);
 
 std::vector<int32_t> tokenize_hviske_prompt(
     const HviskeAssets & assets,

model_specs/citrinet_asr.json

@@ -0,0 +1,34 @@
+{
+  "family": "citrinet_asr",
+  "sources": [
+    {
+      "format": "gguf",
+      "roots": {
+        "model": ".",
+        "weights": "$gguf"
+      },
+      "files": {
+        "config": "model:citrinet_256_config.json",
+        "tokenizer": "model:citrinet_256_tokenizer.model",
+        "vocab": "model:citrinet_256_vocab.txt"
+      },
+      "tensors": {
+        "weights": "weights:"
+      }
+    },
+    {
+      "format": "safetensors",
+      "roots": {
+        "model": "."
+      },
+      "files": {
+        "config": "model:citrinet_256_config.json",
+        "tokenizer": "model:citrinet_256_tokenizer.model",
+        "vocab": "model:citrinet_256_vocab.txt"
+      },
+      "tensors": {
+        "weights": "model:citrinet_256.safetensors"
+      }
+    }
+  ]
+}

model_specs/hviske_asr.json

@@ -0,0 +1,34 @@
+{
+  "family": "hviske_asr",
+  "sources": [
+    {
+      "format": "gguf",
+      "roots": {
+        "model": ".",
+        "weights": "$gguf"
+      },
+      "files": {
+        "config": "model:config.json",
+        "generation_config": "model:generation_config.json",
+        "tokenizer": "model:tokenizer.model"
+      },
+      "tensors": {
+        "weights": "weights:"
+      }
+    },
+    {
+      "format": "safetensors",
+      "roots": {
+        "model": "."
+      },
+      "files": {
+        "config": "model:config.json",
+        "generation_config": "model:generation_config.json",
+        "tokenizer": "model:tokenizer.model"
+      },
+      "tensors": {
+        "weights": "model:model.safetensors"
+      }
+    }
+  ]
+}

src/models/citrinet_asr/assets.cpp

@@ -1,6 +1,6 @@
 #include "engine/models/citrinet_asr/assets.h"
 
-#include "engine/framework/assets/resource_bundle.h"
+#include "engine/framework/assets/model_package.h"
 #include "engine/framework/assets/tensor_source.h"
 #include "engine/framework/assets/weight_metadata.h"
 #include "engine/framework/io/filesystem.h"
@@ -15,25 +15,6 @@
 namespace engine::models::citrinet_asr {
 namespace io = engine::io;
 namespace asset_meta = engine::assets;
-CitrinetAssetPaths resolve_citrinet_assets(const std::filesystem::path & checkpoint_path) {
-    assets::ResourceBundle resources(checkpoint_path.parent_path());
-    resources.add_file("weights", checkpoint_path);
-    resources.add_file("config", assets::checkpoint_sidecar_config_path(checkpoint_path));
-
-    const auto config = resources.parse_json("config");
-    const auto * vocab_file = config.find("vocab_file");
-    if (vocab_file == nullptr || !vocab_file->is_string()) {
-        throw std::runtime_error("Citrinet config is missing vocab_file");
-    }
-    resources.add_model_file("vocab", vocab_file->as_string());
-
-    CitrinetAssetPaths paths;
-    paths.model_root = resources.model_root();
-    paths.checkpoint_path = resources.require_file("weights");
-    paths.config_path = resources.require_file("config");
-    paths.vocab_path = resources.require_file("vocab");
-    return paths;
-}
 
 namespace {
 
@@ -153,20 +134,17 @@ CitrinetConfig parse_config(const io::json::Value & root) {
     return cfg;
 }
 
-CitrinetWeights load_citrinet_weights(const std::filesystem::path & checkpoint_path) {
-    const auto assets = resolve_citrinet_assets(checkpoint_path);
+CitrinetWeights load_citrinet_weights(engine::assets::ResourceBundle resources) {
     CitrinetWeights weights;
-    engine::assets::ResourceBundle resources(assets.model_root);
-    resources.add_file("weights", assets.checkpoint_path);
     const auto source = resources.open_tensor_source("weights");
     weights.source = source;
-    weights.config = parse_config(io::json::parse_file(assets.config_path));
+    weights.config = parse_config(resources.parse_json("config"));
     weights.window = source->require_f32("preprocessor.featurizer.window", {weights.config.win_length});
     weights.fb = source->require_f32(
         "preprocessor.featurizer.fb",
         {1, weights.config.n_mels, weights.config.n_fft / 2 + 1});
 
-    weights.vocab = load_vocab_file(assets.vocab_path);
+    weights.vocab = load_vocab_file(resources.require_file("vocab"));
     if (static_cast<int64_t>(weights.vocab.size()) != weights.config.vocab_size) {
         throw std::runtime_error("vocab size mismatch");
     }
@@ -262,10 +240,13 @@ std::string checkpoint_cache_key(const std::filesystem::path & checkpoint_path)
 
 }  // namespace
 
-std::shared_ptr<const CitrinetWeights> load_citrinet_weights_cached(const std::filesystem::path & checkpoint_path) {
+std::shared_ptr<const CitrinetWeights> load_citrinet_weights_cached(const std::filesystem::path & model_path) {
     static std::mutex cache_mutex;
     static std::unordered_map<std::string, std::weak_ptr<const CitrinetWeights>> cache;
-    const auto key = checkpoint_cache_key(checkpoint_path);
+    auto resources = engine::assets::load_resource_bundle_from_package_spec(
+        model_path,
+        engine::assets::default_model_package_spec_path("citrinet_asr"));
+    const auto key = checkpoint_cache_key(resources.require_file("weights"));
     {
         std::lock_guard<std::mutex> lock(cache_mutex);
         if (const auto it = cache.find(key); it != cache.end()) {
@@ -274,7 +255,7 @@ std::shared_ptr<const CitrinetWeights> load_citrinet_weights_cached(const std::f
             }
         }
     }
-    auto loaded = std::make_shared<const CitrinetWeights>(load_citrinet_weights(checkpoint_path));
+    auto loaded = std::make_shared<const CitrinetWeights>(load_citrinet_weights(std::move(resources)));
     {
         std::lock_guard<std::mutex> lock(cache_mutex);
         cache[key] = loaded;