refactor(backends): self-describing WrappedServer backends (#2287)

.github/workflows/docs_and_style.yml

@@ -24,6 +24,23 @@ jobs:
       - name: Run app regression tests
         run: node test/app/run-app-regression-tests.cjs
 
+  backend-docs-drift:
+    # The backend reference doc (docs/dev/backends-reference.md) is generated from
+    # the self-describing backend descriptors. Build lemond, regenerate, and fail
+    # if the committed doc is stale — the same guarantee a lint provides.
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-backend-docs-${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v5
+      - name: Configure and install build dependencies
+        run: ./setup.sh
+      - name: Build lemond
+        run: cmake --build --preset default --target lemond
+      - name: Check backend reference docs are up to date
+        run: python3 docs/tools/gen_backend_docs.py --check
+
   markdown-link-check:
     runs-on: ubuntu-latest
     concurrency:

CMakeLists.txt

@@ -607,15 +607,6 @@ set(SOURCES_CORE
     src/cpp/server/utils/wmi_helper.cpp
     src/cpp/server/utils/network_beacon.cpp
     src/cpp/server/utils/tcp_jsonl_client.cpp
-    src/cpp/server/backends/cloud_server.cpp
-    src/cpp/server/backends/llamacpp_server.cpp
-    src/cpp/server/backends/fastflowlm_server.cpp
-    src/cpp/server/backends/ryzenaiserver.cpp
-    src/cpp/server/backends/whisper_server.cpp
-    src/cpp/server/backends/moonshine_server.cpp
-    src/cpp/server/backends/kokoro_server.cpp
-    src/cpp/server/backends/sd_server.cpp
-    src/cpp/server/backends/vllm_server.cpp
     src/cpp/server/backends/backend_utils.cpp
     src/cpp/server/backend_manager.cpp
     src/cpp/server/ollama_api.cpp
@@ -647,6 +638,83 @@ elseif(UNIX)
     list(APPEND SOURCES_CORE src/cpp/server/utils/platform/process_unix.cpp)
 endif()
 
+# ============================================================
+# Self-describing backends registry
+# ============================================================
+# The authoritative backend list. Each entry is "<recipe>|<stem>":
+#   recipe - the recipe string used in server_models.json (may contain dashes)
+#   stem   - identifier-safe name and folder. Each backend lives in its own
+#            folder, shipping (in namespace lemon::backends::<stem>):
+#              include/lemon/backends/<stem>/<stem>.h         inline const descriptor (CLI-safe data)
+#              include/lemon/backends/<stem>/<stem>_server.h  WrappedServer subclass + create() decl
+#              server/backends/<stem>/<stem>_server.cpp       implementation + create() def
+#
+# Adding a backend is one line here plus that folder. The foreach below compiles
+# the server source and regenerates the registry headers, which bind each
+# descriptor to its create(). Because this list is a tracked input, editing it
+# forces regeneration on the next build (a file(GLOB) would silently miss a
+# newly added backend). The descriptor is a header-only inline const, so it links
+# into both the lemonade CLI and lemond; only lemond links the server sources.
+set(LEMON_BACKENDS
+    # "<recipe>|<stem>"
+    "llamacpp|llamacpp"
+    "whispercpp|whispercpp"
+    "moonshine|moonshine"
+    "kokoro|kokoro"
+    "sd-cpp|sdcpp"
+    "flm|fastflowlm"
+    "ryzenai-llm|ryzenai"
+    "vllm|vllm"
+    "cloud|cloud"
+)
+
+set(LEMON_DESCRIPTOR_INCLUDES "")
+set(LEMON_DESCRIPTOR_ENTRIES "")
+set(LEMON_FACTORY_INCLUDES "")
+set(LEMON_FACTORY_ENTRIES "")
+# The data registry (descriptors, header-only) links into both binaries; the
+# factory registry + per-backend server sources are server-only.
+# Absolute paths so the CLI subdirectory can reuse LEMON_BACKEND_DESCRIPTOR_SOURCES.
+set(LEMON_BACKEND_DESCRIPTOR_SOURCES
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/server/backends/backend_descriptor_registry.cpp)
+set(LEMON_BACKEND_FACTORY_SOURCES
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/server/backends/backend_registry.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/server/backends/backend_ops.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/server/backends/hf_cache_util.cpp)
+foreach(_backend_entry ${LEMON_BACKENDS})
+    string(REPLACE "|" ";" _backend_parts "${_backend_entry}")
+    list(GET _backend_parts 1 _backend_stem)
+    # The descriptor is header-only (no source). Compile every .cpp in the
+    # backend's folder (server class + any backend-private helpers like GGUF
+    # parsing) — CONFIGURE_DEPENDS re-globs when a file is added/removed so a new
+    # helper in a folder needs no CMake edit. (The backend LIST is still explicit
+    # above so a whole new backend is never silently missed.)
+    file(GLOB _backend_srcs CONFIGURE_DEPENDS
+        ${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/server/backends/${_backend_stem}/*.cpp)
+    list(APPEND LEMON_BACKEND_FACTORY_SOURCES ${_backend_srcs})
+    string(APPEND LEMON_DESCRIPTOR_INCLUDES
+        "#include \"lemon/backends/${_backend_stem}/${_backend_stem}.h\"\n")
+    string(APPEND LEMON_DESCRIPTOR_ENTRIES
+        "        &lemon::backends::${_backend_stem}::descriptor,\n")
+    string(APPEND LEMON_FACTORY_INCLUDES
+        "#include \"lemon/backends/${_backend_stem}/${_backend_stem}_server.h\"\n")
+    string(APPEND LEMON_FACTORY_ENTRIES
+        "        { &lemon::backends::${_backend_stem}::descriptor, &lemon::backends::${_backend_stem}::create, lemon::backends::${_backend_stem}::spec(), lemon::backends::${_backend_stem}::ops() },\n")
+endforeach()
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/server/backends/backend_descriptors_generated.h.in
+    ${CMAKE_CURRENT_BINARY_DIR}/include/backend_descriptors_generated.h
+    @ONLY)
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/cpp/server/backends/backend_factories_generated.h.in
+    ${CMAKE_CURRENT_BINARY_DIR}/include/backend_factories_generated.h
+    @ONLY)
+
+# lemond gets both descriptor data and factories; the CLI gets only the data
+# (see src/cpp/cli/CMakeLists.txt, which reuses LEMON_BACKEND_DESCRIPTOR_SOURCES).
+list(APPEND SOURCES_CORE ${LEMON_BACKEND_DESCRIPTOR_SOURCES} ${LEMON_BACKEND_FACTORY_SOURCES})
+
 # ============================================================
 # Server core OBJECT library (shared by lemond and Lemonade.exe)
 # ============================================================

README.md

@@ -123,6 +123,7 @@ Use `lemonade pull` or the built-in **Model Manager** to download models. You ca
 
 Lemonade supports multiple inference engines for LLM, speech, TTS, and image generation, and each has its own backend and hardware requirements.
 
+<!-- BEGIN GENERATED: backends-matrix -->
 <table>
   <thead>
     <tr>
@@ -137,107 +138,128 @@ Lemonade supports multiple inference engines for LLM, speech, TTS, and image gen
     <tr>
       <td rowspan="9"><strong>Text generation</strong></td>
       <td rowspan="6"><code>llamacpp</code></td>
-      <td><code>vulkan</code></td>
-      <td><code>x86_64</code> CPU, AMD iGPU, AMD dGPU; ARM64 CPU/GPU (Linux)</td>
-      <td>Windows, Linux</td>
+      <td><code>system</code></td>
+      <td><code>x86_64</code>/ARM64 CPU, GPU</td>
+      <td>Linux</td>
     </tr>
     <tr>
-      <td><code>rocm</code></td>
-      <td>Supported AMD ROCm iGPU/dGPU families*</td>
-      <td>Windows, Linux</td>
+      <td><code>metal</code></td>
+      <td>Apple Silicon GPU</td>
+      <td>macOS</td>
     </tr>
     <tr>
       <td><code>cuda</code></td>
       <td>NVIDIA GPUs (Turing or newer)**</td>
       <td>Windows, Linux</td>
     </tr>
     <tr>
-      <td><code>cpu</code></td>
-      <td><code>x86_64</code> CPU; ARM64 CPU (Linux)</td>
+      <td><code>vulkan</code></td>
+      <td><code>x86_64</code> CPU, AMD iGPU, AMD dGPU; ARM64 CPU/GPU (Linux)</td>
       <td>Windows, Linux</td>
     </tr>
     <tr>
-      <td><code>metal</code></td>
-      <td>Apple Silicon GPU</td>
-      <td>macOS</td>
+      <td><code>rocm</code></td>
+      <td>Supported AMD ROCm iGPU/dGPU families*</td>
+      <td>Windows, Linux</td>
     </tr>
     <tr>
-      <td><code>system</code></td>
-      <td><code>x86_64</code>/ARM64 CPU, GPU</td>
-      <td>Linux</td>
+      <td><code>cpu</code></td>
+      <td><code>x86_64</code> CPU; ARM64 CPU (Linux)</td>
+      <td>Windows, Linux</td>
     </tr>
     <tr>
-      <td><code>flm</code></td>
+      <td rowspan="1"><code>flm</code></td>
       <td><code>npu</code></td>
       <td>XDNA2 NPU</td>
       <td>Windows, Linux</td>
     </tr>
     <tr>
-      <td><code>ryzenai-llm</code></td>
+      <td rowspan="1"><code>ryzenai-llm</code></td>
       <td><code>npu</code></td>
       <td>XDNA2 NPU</td>
       <td>Windows</td>
     </tr>
     <tr>
-      <td><code>vllm</code> (experimental)</td>
+      <td rowspan="1"><code>vllm</code> (experimental)</td>
       <td><code>rocm</code></td>
       <td>Strix Halo iGPU (gfx1151)</td>
       <td>Linux</td>
     </tr>
     <tr>
-      <td rowspan="4"><strong>Speech-to-text</strong></td>
-      <td rowspan="3"><code>whispercpp</code></td>
+      <td rowspan="6"><strong>Speech-to-text</strong></td>
+      <td rowspan="5"><code>whispercpp</code></td>
       <td><code>npu</code></td>
       <td>XDNA2 NPU</td>
       <td>Windows</td>
     </tr>
+    <tr>
+      <td><code>rocm</code></td>
+      <td>Supported AMD ROCm iGPU/dGPU families*</td>
+      <td>Windows, Linux</td>
+    </tr>
     <tr>
       <td><code>vulkan</code></td>
       <td><code>x86_64</code> CPU</td>
-      <td>Linux</td>
+      <td>Windows, Linux</td>
     </tr>
     <tr>
       <td><code>cpu</code></td>
       <td><code>x86_64</code> CPU</td>
       <td>Windows, Linux</td>
     </tr>
     <tr>
-      <td><code>moonshine</code></td>
+      <td><code>metal</code></td>
+      <td>Apple Silicon GPU</td>
+      <td>macOS</td>
+    </tr>
+    <tr>
+      <td rowspan="1"><code>moonshine</code></td>
       <td><code>cpu</code></td>
       <td><code>x86_64</code>/<code>arm64</code> CPU</td>
       <td>Windows, Linux, macOS</td>
     </tr>
     <tr>
-      <td><strong>Text-to-speech</strong></td>
-      <td><code>kokoro</code></td>
+      <td rowspan="2"><strong>Text-to-speech</strong></td>
+      <td rowspan="2"><code>kokoro</code></td>
       <td><code>cpu</code></td>
       <td><code>x86_64</code> CPU</td>
       <td>Windows, Linux</td>
     </tr>
     <tr>
-      <td rowspan="4"><strong>Image generation</strong></td>
-      <td rowspan="4"><code>sd-cpp</code></td>
-      <td><code>rocm</code></td>
-      <td>Supported AMD ROCm iGPU/dGPU families*</td>
-      <td>Windows, Linux</td>
+      <td><code>metal</code></td>
+      <td>Apple Silicon GPU</td>
+      <td>macOS</td>
     </tr>
     <tr>
-      <td><code>vulkan</code></td>
-      <td>Vulkan-capable GPUs</td>
+      <td rowspan="5"><strong>Image generation</strong></td>
+      <td rowspan="5"><code>sd-cpp</code></td>
+      <td><code>rocm</code></td>
+      <td>Supported AMD ROCm iGPU/dGPU families*</td>
       <td>Windows, Linux</td>
     </tr>
     <tr>
       <td><code>cuda</code></td>
       <td>NVIDIA GPUs (Turing or newer)**</td>
       <td>Linux</td>
     </tr>
+    <tr>
+      <td><code>vulkan</code></td>
+      <td>Vulkan-capable GPUs</td>
+      <td>Windows, Linux</td>
+    </tr>
     <tr>
       <td><code>cpu</code></td>
       <td><code>x86_64</code> CPU</td>
       <td>Windows, Linux</td>
     </tr>
+    <tr>
+      <td><code>metal</code></td>
+      <td>Apple Silicon GPU</td>
+      <td>macOS</td>
+    </tr>
   </tbody>
 </table>
+<!-- END GENERATED: backends-matrix -->
 
 To check exactly which recipes/backends are supported on your own machine, run:
 

docs/assets/models.js

@@ -2,25 +2,25 @@ const GITHUB_REPO = 'lemonade-sdk/lemonade';
 const TAGS_URL = `https://api.github.com/repos/${GITHUB_REPO}/tags?per_page=100`;
 const RAW_BASE = 'https://raw.githubusercontent.com/lemonade-sdk/lemonade';
 
+/* BEGIN GENERATED: models-js-recipes */
 const RECIPE_PRIORITY = [
   'llamacpp',
   'ryzenai-llm',
   'flm',
   'whispercpp',
   'sd-cpp',
-  'oga-hybrid',
-  'oga-npu',
-  'oga-cpu',
   'kokoro'
 ];
 
 const RECIPE_DISPLAY_NAMES = {
   llamacpp: 'llama.cpp GPU',
-  'ryzenai-llm': 'Ryzen AI SW NPU',
-  flm: 'FastFlowLM NPU',
   whispercpp: 'whisper.cpp',
-  'sd-cpp': 'stable-diffusion.cpp'
+  'sd-cpp': 'stable-diffusion.cpp',
+  flm: 'FastFlowLM NPU',
+  'ryzenai-llm': 'Ryzen AI SW NPU',
+  vllm: 'vLLM ROCm (experimental)'
 };
+/* END GENERATED: models-js-recipes */
 
 const state = {
   tag: null,