refactor: fold RAG backend into rac_commons, remove separate RAG binary

- Changed rac_backend_rag from SHARED/STATIC to OBJECT library (CMake)
- RAG objects folded into rac_commons at compile time
- Moved ONNX embedding provider to rac_backend_onnx to break shared-lib cycle
- ONNX backend now registers embeddings provider during rac_backend_onnx_register()
- Removed RAG as separate backend from all build scripts and SDK configs
- Updated Android, Kotlin, Flutter, React Native build/distribution pipelines
- RAG JNI bridge (librac_backend_rag_jni.so) remains as thin wrapper linking rac_commons

Author: shubhammalhotra28

sdk/runanywhere-commons/CMakeLists.txt

@@ -412,8 +412,23 @@ if(RAC_BUILD_BACKENDS)
     endif()
 
     if(RAC_BACKEND_RAG AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/src/features/rag/CMakeLists.txt")
-        message(STATUS "  - RAG pipeline (USearch)")
+        message(STATUS "  - RAG pipeline (USearch) — folded into rac_commons")
         add_subdirectory(src/features/rag)
+
+        # RAG is an OBJECT library. Fold its compiled objects into rac_commons
+        # so there is no separate librac_backend_rag binary to distribute.
+        target_sources(rac_commons PRIVATE $<TARGET_OBJECTS:rac_backend_rag>)
+
+        # Propagate RAG's non-cyclic dependencies manually.
+        # We intentionally do NOT use target_link_libraries(rac_commons PRIVATE rac_backend_rag)
+        # because that would transitively pull in rac_backend_onnx (via the ONNX embedding
+        # provider) and create a shared-library cycle:
+        #   rac_commons -> rac_backend_rag -> rac_backend_onnx -> rac_commons
+        # nlohmann_json is already linked project-wide (line 116).
+        # Apple frameworks used by RAG (Accelerate) need explicit propagation.
+        if(APPLE)
+            target_link_libraries(rac_commons PUBLIC "-framework Accelerate")
+        endif()
     endif()
 endif()
 
@@ -480,7 +495,10 @@ if(APPLE AND RAC_BUILD_PLATFORM)
     message(STATUS "  Platform:     Apple Foundation Models, System TTS")
 endif()
 if(RAC_BUILD_BACKENDS)
-    message(STATUS "  Backends:     LlamaCPP=${RAC_BACKEND_LLAMACPP}, ONNX=${RAC_BACKEND_ONNX}, WhisperCPP=${RAC_BACKEND_WHISPERCPP}, WhisperKitCoreML=${RAC_BACKEND_WHISPERKIT_COREML}, RAG=${RAC_BACKEND_RAG}")
+    message(STATUS "  Backends:     LlamaCPP=${RAC_BACKEND_LLAMACPP}, ONNX=${RAC_BACKEND_ONNX}, WhisperCPP=${RAC_BACKEND_WHISPERCPP}, WhisperKitCoreML=${RAC_BACKEND_WHISPERKIT_COREML}")
+    if(RAC_BACKEND_RAG)
+        message(STATUS "  RAG pipeline: Enabled (folded into rac_commons)")
+    endif()
 endif()
 if(RAC_BUILD_SERVER)
     message(STATUS "  Server:       OpenAI-compatible HTTP server (runanywhere-server)")

sdk/runanywhere-commons/scripts/build-android.sh

@@ -5,7 +5,7 @@
 # Unified Android build script - builds JNI bridge + selected backends
 #
 # Usage: ./build-android.sh [options] [backends] [abis]
-#        backends: onnx | llamacpp | whispercpp | tflite | rag | all (default: all)
+#        backends: onnx | llamacpp | whispercpp | tflite | all (default: all)
 #                  - onnx: STT/TTS/VAD (Sherpa-ONNX models)
 #                  - llamacpp: LLM text generation (GGUF models)
 #                  - all: onnx + llamacpp (default)
@@ -210,16 +210,13 @@ BUILD_ONNX=OFF
 BUILD_LLAMACPP=OFF
 BUILD_WHISPERCPP=OFF
 BUILD_TFLITE=OFF
-BUILD_RAG=OFF
-
-VALID_BACKENDS="onnx llamacpp whispercpp tflite rag all"
+VALID_BACKENDS="onnx llamacpp whispercpp tflite all"
 
 if [[ "$BACKENDS" == "all" ]]; then
     # NOTE: WhisperCPP is deprecated - use ONNX for STT instead
     # WhisperCPP has build issues with newer ggml versions (GGML_KQ_MASK_PAD)
     BUILD_ONNX=ON
     BUILD_LLAMACPP=ON
-    BUILD_RAG=ON
     BUILD_WHISPERCPP=OFF
 else
     # Parse comma-separated backends list
@@ -230,11 +227,10 @@ else
             llamacpp)   BUILD_LLAMACPP=ON ;;
             whispercpp) BUILD_WHISPERCPP=ON ;;
             tflite)     BUILD_TFLITE=ON ;;
-            rag)        BUILD_RAG=ON ;;
             *)
                 print_error "Unknown backend: $backend"
                 echo "Usage: $0 [backends] [abis]"
-                echo "  backends: onnx | llamacpp | whispercpp | tflite | rag | all"
+                echo "  backends: onnx | llamacpp | whispercpp | tflite | all"
                 echo "  abis: comma-separated list (default: arm64-v8a)"
                 exit 1
                 ;;
@@ -249,7 +245,6 @@ SINGLE_BACKEND=""
 [[ "$BUILD_LLAMACPP" == "ON" ]]   && ((ENABLED_COUNT++)) && SINGLE_BACKEND="llamacpp"
 [[ "$BUILD_WHISPERCPP" == "ON" ]] && ((ENABLED_COUNT++)) && SINGLE_BACKEND="whispercpp"
 [[ "$BUILD_TFLITE" == "ON" ]]     && ((ENABLED_COUNT++)) && SINGLE_BACKEND="tflite"
-[[ "$BUILD_RAG" == "ON" ]]        && ((ENABLED_COUNT++)) && SINGLE_BACKEND="rag"
 
 if [[ "$ENABLED_COUNT" -eq 1 ]]; then
     DIST_SUBDIR="$SINGLE_BACKEND"
@@ -258,7 +253,7 @@ else
 fi
 
 print_header "RunAnywhere Android Build (Unified)"
-echo "Backends: ONNX=$BUILD_ONNX, LlamaCPP=$BUILD_LLAMACPP, WhisperCPP=$BUILD_WHISPERCPP, TFLite=$BUILD_TFLITE, RAG=$BUILD_RAG"
+echo "Backends: ONNX=$BUILD_ONNX, LlamaCPP=$BUILD_LLAMACPP, WhisperCPP=$BUILD_WHISPERCPP, TFLite=$BUILD_TFLITE"
 echo "ABIs: ${ABIS}"
 echo "Android API Level: ${ANDROID_API_LEVEL}"
 echo "Output: dist/android/${DIST_SUBDIR}/"
@@ -360,7 +355,7 @@ for ABI in "${ABI_ARRAY[@]}"; do
         -DRAC_BACKEND_ONNX=${BUILD_ONNX} \
         -DRAC_BACKEND_LLAMACPP=${BUILD_LLAMACPP} \
         -DRAC_BACKEND_WHISPERCPP=${BUILD_WHISPERCPP} \
-        -DRAC_BACKEND_RAG=${BUILD_RAG} \
+        -DRAC_BACKEND_RAG=ON \
         -DRAC_BUILD_TESTS=OFF \
         -DRAC_BUILD_SHARED=ON \
         -DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON \
@@ -590,19 +585,11 @@ for ABI in "${ABI_ARRAY[@]}"; do
         fi
     fi
 
-    # RAG pipeline
-    mkdir -p "${DIST_DIR}/rag/${ABI}"
-    if [ -f "${ABI_BUILD_DIR}/src/features/rag/librac_backend_rag.so" ]; then
-        cp "${ABI_BUILD_DIR}/src/features/rag/librac_backend_rag.so" "${DIST_DIR}/rag/${ABI}/"
-        echo "  Copied: librac_backend_rag.so -> rag/${ABI}/"
-    fi
-
-    # Copy JNI bridge library for RAG
+    # RAG JNI bridge (RAG pipeline is compiled into librac_commons.so;
+    # the JNI bridge is still a thin separate .so that links against rac_commons)
     if [ -f "${ABI_BUILD_DIR}/src/features/rag/librac_backend_rag_jni.so" ]; then
-        cp "${ABI_BUILD_DIR}/src/features/rag/librac_backend_rag_jni.so" "${DIST_DIR}/rag/${ABI}/"
-        echo "  Copied: librac_backend_rag_jni.so -> rag/${ABI}/"
-    else
-        print_warning "librac_backend_rag_jni.so not found - JNI bridge not built by CMake"
+        cp "${ABI_BUILD_DIR}/src/features/rag/librac_backend_rag_jni.so" "${JNI_DIST_DIR}/${ABI}/"
+        echo "  Copied: librac_backend_rag_jni.so -> jni/${ABI}/"
     fi
 
     # TFLite backend
@@ -712,13 +699,6 @@ if [ "$BUILD_WHISPERCPP" = "ON" ]; then
     done
 fi
 
-echo "├── rag/                      # RAG pipeline libraries"
-for ABI in "${ABI_ARRAY[@]}"; do
-    echo "│   └── ${ABI}/"
-    echo "│       ├── librac_backend_rag.so"
-    echo "│       └── librac_backend_rag_jni.so"
-done
-
 if [ "$BUILD_TFLITE" = "ON" ]; then
     echo "└── tflite/                   # TFLite backend libraries"
     for ABI in "${ABI_ARRAY[@]}"; do
@@ -747,9 +727,6 @@ if [ "$BUILD_WHISPERCPP" = "ON" ]; then
     ls -lh "${DIST_DIR}/whispercpp"/*/*.so 2>/dev/null | awk '{print "    " $NF ": " $5}' || echo "    (no files)"
 fi
 
-echo "  RAG:"
-ls -lh "${DIST_DIR}/rag"/*/*.so 2>/dev/null | awk '{print "    " $NF ": " $5}' || echo "    (no files)"
-
 echo ""
 echo -e "${GREEN}Build complete!${NC}"
 

sdk/runanywhere-commons/scripts/build-ios.sh

@@ -729,43 +729,11 @@ main() {
         build_macos
     fi
 
-    # Step 3: Merge RAG pipeline into rac_commons (RAG is a feature, not a separate backend)
-    if [[ "$SKIP_BACKENDS" != true ]]; then
-        log_step "Merging RAG pipeline into rac_commons..."
-        local MERGE_PLATFORMS="OS SIMULATORARM64 SIMULATOR"
-        if [[ "$INCLUDE_MACOS" == true ]]; then
-            MERGE_PLATFORMS="$MERGE_PLATFORMS MACOS"
-        fi
-        for PLATFORM in $MERGE_PLATFORMS; do
-            local PLATFORM_DIR="${BUILD_DIR}/${PLATFORM}"
-            local COMMONS_LIB="${PLATFORM_DIR}/librac_commons.a"
-            local RAG_LIB=""
-
-            for possible_path in \
-                "${PLATFORM_DIR}/src/features/rag/librac_backend_rag.a" \
-                "${PLATFORM_DIR}/src/backends/rag/librac_backend_rag.a" \
-                "${PLATFORM_DIR}/librac_backend_rag.a"; do
-                if [[ -f "$possible_path" ]]; then
-                    RAG_LIB="$possible_path"
-                    break
-                fi
-            done
-
-            if [[ -n "$RAG_LIB" && -f "$COMMONS_LIB" ]]; then
-                libtool -static -o "${COMMONS_LIB}.merged" "$COMMONS_LIB" "$RAG_LIB"
-                mv "${COMMONS_LIB}.merged" "$COMMONS_LIB"
-                log_info "  ${PLATFORM}: Merged librac_backend_rag.a into librac_commons.a"
-            elif [[ -f "$COMMONS_LIB" ]]; then
-                log_warn "  ${PLATFORM}: librac_backend_rag.a not found — RAG not merged"
-            fi
-        done
-    fi
-
-    # Step 4: Create RACommons.xcframework (now includes RAG pipeline)
+    # Step 3: Create RACommons.xcframework (includes RAG pipeline via CMake OBJECT library)
     log_header "Creating XCFrameworks"
     create_xcframework "rac_commons" "RACommons"
 
-    # Step 5: Create backend XCFrameworks
+    # Step 4: Create backend XCFrameworks
     if [[ "$SKIP_BACKENDS" != true ]]; then
         if [[ "$BUILD_BACKEND" == "all" || "$BUILD_BACKEND" == "llamacpp" ]]; then
             create_backend_xcframework "llamacpp" "RABackendLLAMACPP"

sdk/runanywhere-commons/src/backends/onnx/CMakeLists.txt

@@ -180,6 +180,17 @@ set(ONNX_BACKEND_SOURCES
     wakeword_onnx.cpp
 )
 
+# ONNX embedding provider lives in src/features/rag/ but is compiled here
+# to avoid a shared-library cycle: rac_commons -> rac_backend_rag -> rac_backend_onnx -> rac_commons.
+set(RAG_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../features/rag")
+if(RAC_BACKEND_RAG AND EXISTS "${RAG_DIR}/onnx_embedding_provider.cpp")
+    list(APPEND ONNX_BACKEND_SOURCES
+        ${RAG_DIR}/onnx_embedding_provider.cpp
+        ${RAG_DIR}/rac_onnx_embeddings_register.cpp
+    )
+    message(STATUS "  ONNX embedding provider: Compiled into rac_backend_onnx (from RAG dir)")
+endif()
+
 set(ONNX_BACKEND_HEADERS
     onnx_backend.h
 )
@@ -199,6 +210,11 @@ target_include_directories(rac_backend_onnx PUBLIC
     ${RAC_COMMONS_ROOT_DIR}/include/rac/backends
 )
 
+# RAG embedding provider headers (onnx_embedding_provider.h lives in features/rag/)
+if(RAC_BACKEND_RAG AND EXISTS "${RAG_DIR}/onnx_embedding_provider.h")
+    target_include_directories(rac_backend_onnx PRIVATE ${RAG_DIR})
+endif()
+
 # Define RAC_ONNX_BUILDING to export symbols with visibility("default")
 # Define RAC_HAS_ONNX to enable ONNX Runtime code paths
 target_compile_definitions(rac_backend_onnx PRIVATE RAC_ONNX_BUILDING RAC_HAS_ONNX)

sdk/runanywhere-commons/src/backends/onnx/rac_backend_onnx_register.cpp

@@ -9,6 +9,7 @@
 #include "rac_stt_onnx.h"
 #include "rac_tts_onnx.h"
 #include "rac_vad_onnx.h"
+#include "rac/backends/rac_embeddings_onnx.h"
 
 #include <cstdint>
 #include <cstdlib>
@@ -553,8 +554,14 @@ rac_result_t rac_backend_onnx_register(void) {
         return result;
     }
 
+    // Register ONNX embeddings provider (for RAG pipeline).
+    // The provider code is compiled into this backend; registration was
+    // previously done by rac_backend_rag_register() when the sources lived
+    // in the RAG OBJECT library.
+    rac_backend_onnx_embeddings_register();
+
     g_registered = true;
-    RAC_LOG_INFO(LOG_CAT, "ONNX backend registered (STT + TTS + VAD)");
+    RAC_LOG_INFO(LOG_CAT, "ONNX backend registered (STT + TTS + VAD + Embeddings)");
     return RAC_SUCCESS;
 }
 
@@ -563,6 +570,7 @@ rac_result_t rac_backend_onnx_unregister(void) {
         return RAC_ERROR_MODULE_NOT_FOUND;
     }
 
+    rac_backend_onnx_embeddings_unregister();
     rac_model_strategy_unregister(RAC_FRAMEWORK_ONNX);
     rac_service_unregister_provider(VAD_PROVIDER_NAME, RAC_CAPABILITY_VAD);
     rac_service_unregister_provider(TTS_PROVIDER_NAME, RAC_CAPABILITY_TTS);

sdk/runanywhere-commons/src/features/rag/CMakeLists.txt

@@ -50,7 +50,10 @@ if(NOT TARGET nlohmann_json::nlohmann_json)
 endif()
 
 # =============================================================================
-# RAG Pipeline Library (no direct backend dependencies)
+# RAG Pipeline Library (OBJECT — folded into rac_commons at link time)
+#
+# Built as OBJECT so all RAG symbols end up inside librac_commons.{a,so}.
+# There is no separate librac_backend_rag binary to distribute.
 # =============================================================================
 
 set(RAG_PIPELINE_SOURCES
@@ -62,13 +65,10 @@ set(RAG_PIPELINE_SOURCES
     rac_rag_pipeline.cpp
 )
 
-# ONNX embedding provider — wraps as a proper embeddings service backend
-if(TARGET rac_backend_onnx)
-    list(APPEND RAG_PIPELINE_SOURCES
-        onnx_embedding_provider.cpp
-        rac_onnx_embeddings_register.cpp
-    )
-endif()
+# ONNX embedding provider (onnx_embedding_provider.cpp, rac_onnx_embeddings_register.cpp)
+# is compiled into rac_backend_onnx instead of this OBJECT library to avoid a
+# shared-library cycle: rac_commons -> rac_backend_rag -> rac_backend_onnx -> rac_commons.
+# See src/backends/onnx/CMakeLists.txt for where these sources are compiled.
 
 set(RAG_PIPELINE_HEADERS
     rag_backend.h
@@ -77,11 +77,7 @@ set(RAG_PIPELINE_HEADERS
     bm25_index.h
 )
 
-if(RAC_BUILD_SHARED)
-    add_library(rac_backend_rag SHARED ${RAG_PIPELINE_SOURCES} ${RAG_PIPELINE_HEADERS})
-else()
-    add_library(rac_backend_rag STATIC ${RAG_PIPELINE_SOURCES} ${RAG_PIPELINE_HEADERS})
-endif()
+add_library(rac_backend_rag OBJECT ${RAG_PIPELINE_SOURCES} ${RAG_PIPELINE_HEADERS})
 
 target_include_directories(rac_backend_rag PUBLIC
     ${CMAKE_CURRENT_SOURCE_DIR}
@@ -90,18 +86,12 @@ target_include_directories(rac_backend_rag PUBLIC
     ${usearch_SOURCE_DIR}/include
 )
 
-# RAG links against rac_commons for vtable dispatch — NOT against backend libraries
+# nlohmann_json is used by RAG for config parsing.
+# It's header-only (INTERFACE lib) so no link-time cost.
 target_link_libraries(rac_backend_rag PUBLIC
-    rac_commons
     nlohmann_json::nlohmann_json
 )
 
-# ONNX embedding provider needs ONNX Runtime headers for inference
-if(TARGET rac_backend_onnx)
-    target_link_libraries(rac_backend_rag PUBLIC rac_backend_onnx)
-    target_compile_definitions(rac_backend_rag PRIVATE RAG_HAS_ONNX_PROVIDER=1)
-endif()
-
 target_compile_definitions(rac_backend_rag PRIVATE RAC_RAG_BUILDING)
 
 set_target_properties(rac_backend_rag PROPERTIES
@@ -133,10 +123,8 @@ if(RAC_PLATFORM_IOS)
 
 elseif(RAC_PLATFORM_ANDROID)
     message(STATUS "Configuring RAG pipeline for Android")
-    target_link_libraries(rac_backend_rag PRIVATE log)
     target_compile_definitions(rac_backend_rag PRIVATE ORT_API_VERSION=17)
     target_compile_options(rac_backend_rag PRIVATE -O3 -ffunction-sections -fdata-sections)
-    target_link_options(rac_backend_rag PRIVATE -Wl,--gc-sections -Wl,-z,max-page-size=16384)
 
 elseif(RAC_PLATFORM_MACOS)
     message(STATUS "Configuring RAG pipeline for macOS")
@@ -172,8 +160,9 @@ if(RAC_PLATFORM_ANDROID AND RAC_BUILD_SHARED)
             ${RAC_COMMONS_ROOT_DIR}/include
         )
 
+        # RAG symbols live in rac_commons (the OBJECT lib was folded in)
         target_link_libraries(rac_backend_rag_jni PRIVATE
-            rac_backend_rag
+            rac_commons
             log
         )
 

sdk/runanywhere-commons/tests/CMakeLists.txt

@@ -113,7 +113,7 @@ endif()
 # RAG Pipeline Tests (GoogleTest)
 # =============================================================================
 
-if(RAC_BACKEND_RAG AND TARGET rac_backend_rag)
+if(RAC_BACKEND_RAG)
     include(FetchContent)
     find_package(Threads REQUIRED)
 
@@ -133,7 +133,7 @@ if(RAC_BACKEND_RAG AND TARGET rac_backend_rag)
     )
     target_link_libraries(rac_rag_backend_thread_safety_test
         PRIVATE
-        rac_backend_rag
+        rac_commons
         Threads::Threads
         GTest::gtest_main
     )
@@ -153,7 +153,7 @@ if(RAC_BACKEND_RAG AND TARGET rac_backend_rag)
     )
     target_link_libraries(rac_chunker_test
         PRIVATE
-        rac_backend_rag
+        rac_commons
         Threads::Threads
         GTest::gtest_main
     )
@@ -172,7 +172,7 @@ if(RAC_BACKEND_RAG AND TARGET rac_backend_rag)
     )
     target_link_libraries(rac_simple_tokenizer_test
         PRIVATE
-        rac_backend_rag
+        rac_commons
         Threads::Threads
         GTest::gtest_main
     )