Merge remote-tracking branch 'origin/main' into dev

Author: 0xShug0

CMakeLists.txt

@@ -147,6 +147,7 @@ add_library(engine_runtime STATIC
     src/framework/core/backend.cpp
     src/framework/core/deferred_tensor_writer.cpp
     src/framework/core/execution_context.cpp
+    src/framework/core/host_memory.cpp
     src/framework/runtime/registry.cpp
     src/framework/runtime/model.cpp
     src/framework/runtime/session.cpp

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/core/host_memory.h

@@ -0,0 +1,12 @@
+#pragma once
+
+#include <cstddef>
+
+namespace engine::core {
+
+// Physical memory the host still has free, or 0 when it cannot be determined
+// (no portable query on this platform). Callers must treat 0 as "unknown" and
+// fall back to whatever they would have done anyway, never as "no memory".
+size_t available_host_memory_bytes();
+
+}  // namespace engine::core

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;

include/engine/models/qwen3_tts/session.h

@@ -63,6 +63,8 @@ class Qwen3TTSSession final
     size_t speech_decoder_graph_arena_bytes_ = 32ull * 1024ull * 1024ull;
     size_t speaker_encoder_graph_arena_bytes_ = 32ull * 1024ull * 1024ull;
     // No-alloc GGML context capacities for reusable constant tensor descriptors.
+    // Generous on purpose; ConstantTensorCache fits them to the host when it has
+    // to, so a small machine is not asked to reserve what it does not have.
     size_t talker_constant_context_bytes_ = 4ull * 1024ull * 1024ull * 1024ull;
     size_t code_predictor_constant_context_bytes_ = 1536ull * 1024ull * 1024ull;
     size_t speech_decoder_constant_context_bytes_ = 1536ull * 1024ull * 1024ull;

src/framework/core/host_memory.cpp

@@ -0,0 +1,64 @@
+#include "engine/framework/core/host_memory.h"
+
+#if defined(_WIN32)
+#include <windows.h>
+#elif defined(__linux__)
+#include <cstdio>
+#include <cstring>
+#elif defined(__unix__) || defined(__APPLE__)
+#include <unistd.h>
+#endif
+
+namespace engine::core {
+
+#if defined(__linux__)
+namespace {
+
+// MemAvailable: what the kernel estimates a new allocation can get without
+// swapping, counting reclaimable page cache. sysconf(_SC_AVPHYS_PAGES) reports
+// MemFree instead, which sits near zero on any busy machine because spare RAM
+// is used for cache -- reading it as memory pressure would be wrong.
+size_t mem_available_bytes() {
+    std::FILE * meminfo = std::fopen("/proc/meminfo", "r");
+    if (meminfo == nullptr) {
+        return 0;
+    }
+    char line[256];
+    size_t bytes = 0;
+    while (std::fgets(line, sizeof(line), meminfo) != nullptr) {
+        unsigned long long kib = 0;
+        if (std::sscanf(line, "MemAvailable: %llu kB", &kib) == 1) {
+            bytes = static_cast<size_t>(kib) * 1024ull;
+            break;
+        }
+    }
+    std::fclose(meminfo);
+    return bytes;
+}
+
+}  // namespace
+#endif
+
+size_t available_host_memory_bytes() {
+#if defined(_WIN32)
+    MEMORYSTATUSEX status{};
+    status.dwLength = sizeof(status);
+    if (GlobalMemoryStatusEx(&status)) {
+        return static_cast<size_t>(status.ullAvailPhys);
+    }
+#elif defined(__linux__)
+    if (const size_t bytes = mem_available_bytes(); bytes > 0) {
+        return bytes;
+    }
+#elif defined(_SC_AVPHYS_PAGES) && defined(_SC_PAGE_SIZE)
+    const long pages = sysconf(_SC_AVPHYS_PAGES);
+    const long page_size = sysconf(_SC_PAGE_SIZE);
+    if (pages > 0 && page_size > 0) {
+        return static_cast<size_t>(pages) * static_cast<size_t>(page_size);
+    }
+#endif
+    // macOS has no _SC_AVPHYS_PAGES, and any query can fail: report unknown.
+    return 0;
+}
+
+}  // namespace engine::core

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);