Merge pull request #74 from lapy/feature/machine-readable-loader-catalog

Add machine-readable loader and package catalog exports

Author: 0xShug0

app/cli/main.cpp

@@ -10,7 +10,9 @@
 #include "engine/framework/audio/chunking.h"
 #include "engine/framework/audio/conversion.h"
 #include "engine/framework/debug/trace.h"
+#include "engine/framework/io/json.h"
 #include "engine/framework/runtime/registry.h"
+#include "engine/framework/runtime/session.h"
 
 #include <algorithm>
 #include <cmath>
@@ -141,7 +143,7 @@ void print_task_list_help() {
         << "    --mode streaming uses the selected model's default streaming policy\n"
         << "  Utility:\n"
         << "    --inspect\n"
-        << "    --list-loaders\n"
+        << "    --list-loaders [--json]\n"
         << "\n"
         << "  Tasks:\n"
         << "    vad    voice activity detection\n"
@@ -564,10 +566,67 @@ int audiocpp_cli_main(int argc, char ** argv) {
             return 0;
         }
         if (has_arg(argc, argv, "--list-loaders")) {
-            const auto families = registry.families();
-            std::cout << "registered_loaders=" << registry.size() << "\n";
-            for (const auto & family : families) {
-                std::cout << family << "\n";
+            const auto advertisements = registry.advertise_loaders();
+            if (has_arg(argc, argv, "--json")) {
+                engine::io::json::Value::Object loaders_object;
+                for (const auto & row : advertisements) {
+                    engine::io::json::Value::Object tasks_object;
+                    for (const auto & task_cap : row.capabilities.supported_tasks) {
+                        engine::io::json::Value::Array modes;
+                        for (const auto mode : task_cap.modes) {
+                            modes.push_back(engine::io::json::Value::make_string(engine::runtime::to_string(mode)));
+                        }
+                        tasks_object.emplace(
+                            engine::runtime::to_string(task_cap.task),
+                            engine::io::json::Value::make_array(std::move(modes)));
+                    }
+                    engine::io::json::Value::Array endpoints;
+                    for (const auto & endpoint : row.api_endpoints) {
+                        endpoints.push_back(engine::io::json::Value::make_string(endpoint));
+                    }
+                    engine::io::json::Value::Object loader_object;
+                    loader_object.emplace("tasks", engine::io::json::Value::make_object(std::move(tasks_object)));
+                    loader_object.emplace(
+                        "instructions_policy",
+                        engine::io::json::Value::make_string(row.instructions_policy));
+                    loader_object.emplace(
+                        "api_endpoints",
+                        engine::io::json::Value::make_array(std::move(endpoints)));
+                    loaders_object.emplace(
+                        row.family,
+                        engine::io::json::Value::make_object(std::move(loader_object)));
+                }
+                engine::io::json::Value::Object root;
+                root.emplace("schema_version", engine::io::json::Value::make_number(1));
+                root.emplace("loaders", engine::io::json::Value::make_object(std::move(loaders_object)));
+                std::cout << engine::io::json::stringify(engine::io::json::Value::make_object(std::move(root)))
+                          << "\n";
+            } else {
+                std::cout << "registered_loaders=" << advertisements.size() << "\n";
+                for (const auto & row : advertisements) {
+                    std::cout << row.family;
+                    if (!row.capabilities.supported_tasks.empty()) {
+                        std::cout << ":";
+                        for (size_t i = 0; i < row.capabilities.supported_tasks.size(); ++i) {
+                            const auto & task_cap = row.capabilities.supported_tasks[i];
+                            if (i > 0) {
+                                std::cout << ",";
+                            }
+                            std::cout << " " << engine::runtime::to_string(task_cap.task);
+                            if (!task_cap.modes.empty()) {
+                                std::cout << " (";
+                                for (size_t m = 0; m < task_cap.modes.size(); ++m) {
+                                    if (m > 0) {
+                                        std::cout << "|";
+                                    }
+                                    std::cout << engine::runtime::to_string(task_cap.modes[m]);
+                                }
+                                std::cout << ")";
+                            }
+                        }
+                    }
+                    std::cout << "\n";
+                }
             }
             return 0;
         }

include/engine/framework/runtime/model.h

@@ -105,6 +105,16 @@ class ILoadedVoiceModel {
         const SessionOptions & options) const = 0;
 };
 
+struct LoaderAdvertisement {
+    std::string family;
+    CapabilitySet capabilities;
+    std::string instructions_policy;
+    std::vector<std::string> api_endpoints;
+};
+
+/** Map advertised capabilities to the HTTP surfaces they normally use. */
+std::vector<std::string> default_api_endpoints_for_capabilities(const CapabilitySet & capabilities);
+
 class IVoiceModelLoader {
 public:
     virtual ~IVoiceModelLoader() = default;
@@ -113,6 +123,15 @@ class IVoiceModelLoader {
     virtual bool can_load(const ModelLoadRequest & request) const = 0;
     virtual ModelInspection inspect(const ModelLoadRequest & request) const = 0;
     virtual std::unique_ptr<ILoadedVoiceModel> load(const ModelLoadRequest & request) const = 0;
+
+    /**
+     * Path-free loader catalog for ``--list-loaders --json``.
+     * Override ``advertised_capabilities`` (and policy when non-default) on each loader.
+     */
+    virtual CapabilitySet advertised_capabilities() const;
+    virtual std::string advertised_instructions_policy() const;
+    virtual std::vector<std::string> advertised_api_endpoints() const;
+    LoaderAdvertisement advertise() const;
 };
 
 }  // namespace engine::runtime

include/engine/framework/runtime/registry.h

@@ -22,6 +22,8 @@ class ModelRegistry {
     size_t size() const noexcept;
     std::vector<std::string> families() const;
     bool supports_family(const std::string & family) const noexcept;
+    /** Path-free loader catalog for ``--list-loaders --json``. */
+    std::vector<LoaderAdvertisement> advertise_loaders() const;
     ModelInspection inspect(const ModelLoadRequest & request) const;
     ModelInspection inspect(const std::filesystem::path & model_path) const;
     std::unique_ptr<ILoadedVoiceModel> load(const ModelLoadRequest & request) const;

src/framework/runtime/model.cpp

@@ -96,4 +96,65 @@ const NamedAsset * select_named_asset(
     return &assets.front();
 }
 
+std::vector<std::string> default_api_endpoints_for_capabilities(const CapabilitySet & capabilities) {
+    bool has_asr = false;
+    bool has_speech = false;
+    bool has_other = false;
+    for (const auto & task : capabilities.supported_tasks) {
+        switch (task.task) {
+        case VoiceTaskKind::Asr:
+            has_asr = true;
+            break;
+        case VoiceTaskKind::Tts:
+        case VoiceTaskKind::VoiceCloning:
+        case VoiceTaskKind::VoiceDesign:
+            has_speech = true;
+            break;
+        default:
+            has_other = true;
+            break;
+        }
+    }
+    if (has_asr && !has_speech && !has_other) {
+        return {"/v1/audio/transcriptions"};
+    }
+    if (has_speech && !has_other) {
+        return {"/v1/audio/speech"};
+    }
+    if (has_speech && has_other) {
+        return {"/v1/tasks/run", "/v1/audio/speech"};
+    }
+    return {"/v1/tasks/run"};
+}
+
+CapabilitySet IVoiceModelLoader::advertised_capabilities() const {
+    // Path-free catalog entry. Each loader overrides with the same task/mode
+    // contract it exposes via inspect/load (without requiring a model path).
+    return {};
+}
+
+std::string IVoiceModelLoader::advertised_instructions_policy() const {
+    // Generic default from advertised tasks. Loaders with a different contract override.
+    for (const auto & task : advertised_capabilities().supported_tasks) {
+        if (task.task == VoiceTaskKind::Tts || task.task == VoiceTaskKind::VoiceDesign
+            || task.task == VoiceTaskKind::VoiceCloning) {
+            return "openai_instruct";
+        }
+    }
+    return "none";
+}
+
+std::vector<std::string> IVoiceModelLoader::advertised_api_endpoints() const {
+    return default_api_endpoints_for_capabilities(advertised_capabilities());
+}
+
+LoaderAdvertisement IVoiceModelLoader::advertise() const {
+    LoaderAdvertisement row;
+    row.family = family();
+    row.capabilities = advertised_capabilities();
+    row.instructions_policy = advertised_instructions_policy();
+    row.api_endpoints = advertised_api_endpoints();
+    return row;
+}
+
 }  // namespace engine::runtime

src/framework/runtime/registry.cpp

@@ -120,6 +120,21 @@ bool ModelRegistry::supports_family(const std::string & family) const noexcept {
     return false;
 }
 
+std::vector<LoaderAdvertisement> ModelRegistry::advertise_loaders() const {
+    std::vector<LoaderAdvertisement> out;
+    out.reserve(loaders_.size());
+    for (const auto & loader : loaders_) {
+        if (loader == nullptr) {
+            continue;
+        }
+        out.push_back(loader->advertise());
+    }
+    std::sort(out.begin(), out.end(), [](const LoaderAdvertisement & a, const LoaderAdvertisement & b) {
+        return a.family < b.family;
+    });
+    return out;
+}
+
 ModelInspection ModelRegistry::inspect(const ModelLoadRequest & request) const {
     engine::assets::ScopedModelPackageSpecOverride spec_override(request.model_spec_override, request.model_path);
     validate_request(request);

src/models/ace_step/loader.cpp

@@ -90,6 +90,14 @@ class AceStepLoader final : public runtime::IVoiceModelLoader {
         return "ace_step";
     }
 
+    runtime::CapabilitySet advertised_capabilities() const override {
+        runtime::CapabilitySet out;
+        out.supported_tasks = {
+            {runtime::VoiceTaskKind::AudioGeneration, {runtime::RunMode::Offline}},
+        };
+        return out;
+    }
+
     bool can_load(const runtime::ModelLoadRequest & request) const override {
         try {
             const auto root = resolve_model_root(request.model_path);

src/models/chatterbox/loader.cpp

@@ -66,6 +66,17 @@ class ChatterboxLoader final : public runtime::IVoiceModelLoader {
         return "chatterbox";
     }
 
+    runtime::CapabilitySet advertised_capabilities() const override {
+        runtime::CapabilitySet out;
+        out.supported_tasks = {
+            {runtime::VoiceTaskKind::VoiceCloning, {runtime::RunMode::Offline}},
+            {runtime::VoiceTaskKind::VoiceConversion, {runtime::RunMode::Offline}},
+        };
+        out.supports_speaker_reference = true;
+        out.supports_style_condition = true;
+        return out;
+    }
+
     bool can_load(const runtime::ModelLoadRequest & request) const override {
         try {
             const auto root = resolve_model_root(request.model_path);

src/models/citrinet_asr/session.cpp

@@ -37,6 +37,15 @@ class CitrinetASRLoader final : public runtime::IVoiceModelLoader {
         return "citrinet_asr";
     }
 
+    runtime::CapabilitySet advertised_capabilities() const override {
+        runtime::CapabilitySet out;
+        out.supported_tasks = {
+            {runtime::VoiceTaskKind::Asr, {runtime::RunMode::Offline}},
+        };
+        out.supports_timestamps = true;
+        return out;
+    }
+
     bool can_load(const runtime::ModelLoadRequest & request) const override {
         if (request.family_hint.has_value() && *request.family_hint != family()) {
             return false;

src/models/demucs/loader.cpp

@@ -40,6 +40,14 @@ class HTDemucsLoader final : public runtime::IVoiceModelLoader {
         return "htdemucs";
     }
 
+    runtime::CapabilitySet advertised_capabilities() const override {
+        runtime::CapabilitySet out;
+        out.supported_tasks = {
+            {runtime::VoiceTaskKind::SourceSeparation, {runtime::RunMode::Offline}},
+        };
+        return out;
+    }
+
     bool can_load(const runtime::ModelLoadRequest & request) const override {
         try {
             const auto package_spec = assets::default_model_package_spec_path(family());

src/models/heartmula/loader.cpp

@@ -84,6 +84,15 @@ class HeartMuLaLoader final : public runtime::IVoiceModelLoader {
         return "heartmula";
     }
 
+    runtime::CapabilitySet advertised_capabilities() const override {
+        runtime::CapabilitySet out;
+        out.supported_tasks = {
+            {runtime::VoiceTaskKind::AudioGeneration, {runtime::RunMode::Offline}},
+        };
+        out.supports_style_condition = true;
+        return out;
+    }
+
     bool can_load(const runtime::ModelLoadRequest & request) const override {
         try {
             const auto root = resolve_model_root(request.model_path);