Rag kotlin (#410)

* feat: Implement RAG (Retrieval-Augmented Generation) with ONNX and LlamaCPP backends

Implement complete on-device RAG with document management,
semantic search, and contextual answer generation.

Core Implementation (runanywhere-commons):
- Implement RAG pipeline with document chunking and vector retrieval
- Implement ONNX embedding provider (all-MiniLM-L6-v2)
- Implement LlamaCPP and ONNX text generators
- Implement USearch-based vector store for fast similarity search
- Implement structured logging with metadata support
- Update CMake build system for RAG backend integration

React Native Integration:
- Create @runanywhere/rag package with TypeScript API
- Add NitroModules global initialization for proper JSI binding
- Generate Nitro bindings for Android and iOS platforms
- Improve model path resolution for ONNX single-file models
- Implement RAG configuration interface with tunable parameters
- Update build scripts for RAG module compilation

Example Application:
- Implement RAGScreen demo with interactive document Q&A
- Implement model selection UI for embedding and LLM models
- Implement document management (add, clear, batch operations)
- Display retrieval sources with similarity scores
- Show timing metrics (retrieval, generation, total)
- Implement model catalog entries for embedding models
- Update navigation to include RAG tab

This enables privacy-preserving RAG with all processing happening
on-device, supporting both ONNX and LlamaCPP backends.

* fix: remove postinstall-postinstall to resolve workspace conflicts

- Remove postinstall-postinstall dependency from example app
- Update example app package-lock.json with refreshed dependencies

* style: Clean code

* feat: Add Vision tab alongside RAG (7 tabs total)

- Added Vision imports (VisionHubScreen, VLMScreen) to TabNavigator
- Extended tab icons with Vision eye icon
- Extended tab labels with Vision label
- Added VisionStackScreen component for Vision hub → VLM navigation
- Updated RootTabParamList type to include Vision tab

Navigation now includes:
1. Chat (default)
2. STT (speech-to-text)
3. TTS (text-to-speech)
4. Voice (voice chat)
5. RAG (retrieval-augmented generation)
6. Vision (image understanding)
7. Settings

Both RAG and Vision features are now accessible from bottom tab navigation.

* fix: Resolve App.tsx merge conflict - combine optional LlamaCPP with all models

* fix: Stub ToolCallingBridge functions pending commons library updates

- Copied rac_tool_calling.h header to core package includes
- Stubbed out ToolCallingBridge function calls in HybridRunAnywhereCore
- Tool calling functions (rac_tool_call_*) not yet available in commons v0.1.4
- Excludes ToolCallingBridge.cpp from Android build until commons is updated
- RAG functionality unaffected - tool calling is separate feature
- Allows Android build to complete successfully with 7-tab navigation

* fix: add missing @react-navigation/native-stack dependency for tab navigation

* style: Clean code

* style: Clean code

* fix: Remove unused imports in RunAnywhere example

Clean up unused imports in the React Native RunAnywhere example: remove LLMFramework from the @runanywhere/core import in App.tsx, and drop IconSize and ModelRequiredOverlay imports from RAGScreen.tsx (keeping Spacing, Padding, BorderRadius). This removes unused symbols and addresses related import warnings.

* style: Clean code

Delete the backup file sdk/runanywhere-commons/src/backends/rag/llamacpp_generator.cpp.bak which contained an older LlamaCPP generator implementation. The file was redundant and is removed to clean up the repository and avoid confusion with the active implementation.

* style: Clean code

* refactor(rag): add proper error handling for ONNX Runtime C API calls

Fixes critical bug where ORT API return statuses were silently ignored
in onnx_embedding_provider.cpp and onnx_generator.cpp, which could cause
undefined behavior and resource leaks on allocation failures.

Solution:
- Create shared ort_guards.h with RAII wrappers (OrtStatusGuard,
  OrtValueGuard, OrtMemoryInfoGuard)
- Refactor onnx_embedding_provider.cpp to use RAII guards
- Refactor onnx_generator.cpp to use RAII guards
- Remove duplicate RAII class definitions

Benefits:
- All ORT API errors now properly checked
- Automatic resource cleanup (exception-safe)
- Eliminates code duplication
- Zero-cost abstraction with compiler optimizations

* refactor(rag): fix critical memory safety and data integrity bugs in RAG backend

This commit addresses four critical bugs in the RAG C++ implementation:

1. ORT status guard memory leak (ort_guards.h, onnx_generator.cpp)
   - Refactored get_address() to be a pure accessor
   - Changed to explicit reset() pattern to prevent memory leaks
   - Fixed dangling pointer issues in onnx_generator.cpp from vector reallocation

2. Hash collision vulnerability (vector_store_usearch.cpp)
   - Replaced std::hash<std::string> with monotonic counter (next_key_)
   - Ensures collision-free key generation for vector store entries
   - Added duplicate detection in add_chunks_batch()

3. Metadata persistence bug (vector_store_usearch.cpp)
   - Implemented JSON serialization for save/load operations
   - Now persists chunks_, id_to_key_, and next_key_ alongside USearch index
   - Added proper deserialization with state reconstruction

These fixes ensure memory safety, prevent silent data loss, and enable
proper state persistence across save/load cycles.

* refactor(rag): enhance ONNX embedding provider with error handling

- Implement OrtSessionOptionsGuard class for automatic session options cleanup
- Fix GetTensorMutableData null-pointer dereference with proper status checking
- Implement error handling for session options creation/configuration
- Replace manual cleanup with RAII pattern (eliminates 3 ReleaseSessionOptions calls)
- Rename status_guard to output_status_guard to fix variable shadowing

This ensures robust error handling, automatic resource cleanup, and proper C++
exception safety in the ONNX embedding provider used by the RAG backend.

All fixes verified with successful Android APK build (arm64-v8a).

* feat(rag): Enhance error handling and debugging for RAG module

Comprehensive improvements to RAG module reliability and debuggability:

**TypeScript (Frontend)**
- Add step-by-step logging in RAG.ts constructor for module initialization
- Track NitroModules proxy availability and hybrid object creation
- Include detailed error messages with stack traces for troubleshooting
- Wrap createRAG() function in try-catch with logging

**C++ Backend (Error Handling)**
- vector_store_usearch.cpp: Add error checking for USearch operations
  * Validate return values for add(), remove(), save(), load()
  * Log detailed error messages for failed vector store operations
  * Gracefully handle batch operation failures

- onnx_generator.cpp: Add robust error checking for ONNX Runtime
  * Validate OrtStatus for all CreateTensorWithDataAsOrtValue calls
  * Check for null tensors (input_ids, attention_mask, position_ids)
  * Release status objects prope
Comprehensive improvements to RAG module reliability and debuggability:

**TypeScript (Frontend)**
- Add step-by-step logging in RAG.ts ceLi
**TypeScript (Frontend)**
- Add step-by-step logging in RAG.ts constr.sh- Add step-by-step loggiso- Track NitroModules proxy availability and hybrid object creation
- Incl0.- Include detailed error messages with stack traces for troubleshnc- Wrap createRAG() function in try-catch with logging

**C++ Backend (Ll
**C++ Backend (Error Handling)**
- vector_store_use
- - vector_store_usearch.cpp: Addea  * Validate return values for add(), remove(), save(), load()
  * Loc  * Log detailed error messages for failed vector store opera

* fix(rag): Harden vector store load/search error handling

- fix arm_fp16 include guard precedence for Apple targets
- make add_chunks_batch report success only when chunks added
- remove noexcept from search to avoid terminate on exceptions
- make load() robust with JSON try/catch and atomic state update

* feat(rag): Add vocab-backed tokenizer and strict embedding setup

- load WordPiece vocab and enforce presence before model init
- add tokenization cache for repeat words
- pass vocab path via embeddingConfigJson
- download vocab.txt as separate ONNX model

* feat(rag): add LRU cache to tokenizer for repeated inputs

* feat(rag): add NEON SIMD tokenization with safe fallback

* fix: modernize Metro config and add secure storage method compatibility

- Replace deprecated exclusionList/blacklistRE with blockList API (metro-config)
- Fixes React Native 0.83.1 build compatibility
- Add dual-method support in SecureStorageService for TypeScript/C++ interop
- Enables fallback between secureStorageStore/Retrieve and secureStorageSet/Get

* fix(rag): correct Android C++ lib name and regenerate Nitrogen outputs

* fix(react-native): Fix RAG module initialization and improve core functionality

Main fix:
- Fix RAG package to use TypeScript source instead of compiled JS
  Changed package.json main entry from 'lib/index.js' to 'src/index.ts'
  This resolves 'Cannot find module' error when initializing RAG
  Aligns with core package structure for proper Metro bundling

Additional improvements:
- Improve Metro module resolution with explicit extraNodeModules mapping
- Add safety flag to prevent duplicate NitroModules native install() calls
- Add semantic aliases for secure storage (Store/Retrieve)
- Remove pre-bundled JS asset to force Metro dev server usage

Fixes React Native Android and iOS RAG module initialization.

* fix(react-native/rag): Refactor iOS build to use commons toolchain system

Replaces direct Xcode generator CMake invocations with commons build-ios.sh
to fix CXX compiler identification failures and create proper XCFrameworks.

Changes:
- Refactored build-ios-libs.sh to call commons/scripts/build-ios.sh instead
  of manually configuring CMake with Xcode generator
- Added lipo step to create universal simulator static libraries (arm64+x86_64)
  before XCFramework creation to avoid duplicate architecture errors
- Removed ~70 lines of duplicate CMake configuration
- Fixed "No known features for CXX compiler" error during simulator builds
- Fixed "Both ios-arm64-simulator and ios-x86_64-simulator represent two
  equivalent library definitions" XCFramework error

Technical Details:
- Leverages proven toolchain-based builds (ios.toolchain.cmake) instead of
  Xcode generator which had compiler identification issues
- Creates universal simulator libs with lipo before bundling into XCFramework
- XCFrameworks now properly contain:
  - ios-arm64/ (device: 1.2M librac_backend_rag.a)
  - ios-arm64_x86_64-simulator/ (universal: 2.4M librac_backend_rag.a)
- Build output verified: iOS 3.6M XCFramework, Android 41M .so libs

Impact:
- iOS builds: More reliable, reuses commons infrastructure
- Android builds: No changes, release APKs unaffected
- React Native integration: Podspec correctly references bundled XCFrameworks

Testing:
- Full --setup --clean build succeeds
- All architectures built (OS arm64, SIMULATORARM64, SIMULATOR x86_64)
- XCFrameworks created successfully with proper structure
- Android JNI libraries unchanged in jniLibs/arm64-v8a/

* fix(react-native/core): Add framework search paths for RACommons.xcframework

The iOS build was failing because RACommons.xcframework headers use
framework-relative includes (e.g., `<RACommons/rac_error.h>`), but
Xcode couldn't locate the framework during compilation.

Changes:
- Added HEADER_SEARCH_PATHS for both device (ios-arm64) and simulator
  (ios-arm64_x86_64-simulator) slices of RACommons.xcframework
- Added FRAMEWORK_SEARCH_PATHS pointing to ios/Binaries directory

This allows both:
1. Direct includes from C++ bridge files (`#include "rac_telemetry_manager.h"`)
2. Framework-relative includes from RACommons headers (`#include <RACommons/rac_error.h>`)

to resolve correctly during the build process.

Fixes: iOS build errors related to missing RACommons headers
Related: PR #349 (RAG improvements)

* fix(react-native/ios): resolve XCFramework and header path issues for iOS build

- Rebuild RACommons.xcframework with ios-arm64_x86_64-simulator slice and embedding category definitions
- Update RAG module to use <RACommons/...> headers on iOS for proper framework resolution
- Add nlohmann/json.hpp header search path to RunAnywhereRAG.podspec
- Copy RABackendLLAMACPP.xcframework from build artifacts to SDK and example node_modules

These changes fix iOS simulator build failures due to missing headers, missing simulator architecture slices, and undefined embedding category symbols.

* Optimize RAG backend: reduce lock contention and fix ORT API version

- Extract config values under lock, minimize critical section
- Move expensive operations (search, generation) outside mutex
- Change embedding_provider and text_generator to shared_ptr for safe copying
- Add search_with_provider() helper to reduce pointer dereferencing
- Inline prompt formatting for performance
- Set ORT_API_VERSION=17 to match bundled libonnxruntime
- Remove redundant library loading in RAGPackage

This reduces blocking time for concurrent access and improves throughput

* Add GTest thread-safety coverage for RAG backend

* Add NDK 26 rebuild helper for Android RAG

* Fix suffix-only model extension stripping

* Harden RAG pipeline creation on failure

* test: Add comprehensive unit tests for RAG backend components

- Add chunker_test.cpp: 24 test cases covering DocumentChunker functionality
  * Basic text processing (empty, single/multi-line)
  * Token estimation and proportionality
  * Configuration customization (chunk size, overlap)
  * Boundary conditions (punctuation, whitespace, special chars)
  * Memory efficiency with large text (100KB+)
  * Move semantics and thread safety

- Add simple_tokenizer_test.cpp: Placeholder for SimpleTokenizer tests
  * Ready for expansion when class is extracted to public interface

- Update CMakeLists.txt: Integrate test targets into build system
  * rac_chunker_test executable with GoogleTest discovery
  * rac_simple_tokenizer_test executable with GoogleTest discovery
  * Proper linking to rac_backend_rag, threads, and GTest

All 29 tests passing (24 chunker + 1 tokenizer placeholder + 1 thread safety + 3 executable tests)
C++17 standard with proper memory management and best practices

* docs(android): document React Native RAG app build workflow

Add REACT_NATIVE_ANDROID_RAG_APP_BUILD.md with:
- rebuild-android-ndk26.sh reference and execution flow
- 4-step build process: clean, build natives, distribute, build APK
- Prerequisites and environment configuration
- Manual step-by-step alternative
- Development iteration cycle (2-3min vs 15+min full rebuild)
- Verification and device testing
- Troubleshooting common issues
- CI/CD integration examples (GitHub Actions, pre-commit hooks)

Targets developers working on RAG+embedding+storage features.

* fixed rag for ios-react-native

Had to change the build scripts a bit to make it work. Llamacpp wasnt included earlier.
Currently this matches the android react native and it has hardcoded docs and doesnt allow user to input docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(01-01): Add RAG C headers to CRACommons umbrella and extend error/event/component enums

- Copy rac_rag_pipeline.h and rac_rag.h to CRACommons/include with flattened include paths
- Add rac_rag_pipeline.h and rac_rag.h to CRACommons.h umbrella header
- Add ErrorCategory.rag case for RAG-categorized errors
- Add SDKComponent.rag case with displayName "Retrieval-Augmented Generation"
- Add EventCategory.rag case for RAG event filtering
- Add SDKError.rag() factory method
- Fix exhaustive switch statements in RunAnywhere+Frameworks.swift and CppBridge+Services.swift

* feat(01-01): Create CppBridge+RAG.swift actor for thread-safe RAG pipeline management

- Add CppBridge.RAG actor following the CppBridge+STT.swift pattern
- Implement createPipeline, destroy, addDocument, clearDocuments, documentCount, query
- All methods delegate to C API (rac_rag_pipeline_create, rac_rag_add_document, etc.)
- Actor provides Swift 6 concurrency-safe access without NSLock
- Guard checks on pipeline handle throw SDKError.rag(.notInitialized) when not created

* feat(01-02): create RAGTypes.swift with Swift wrappers over C RAG types

- RAGConfiguration: wraps rac_rag_config_t with withCConfig sync bridge
- RAGQueryOptions: wraps rac_rag_query_t with withCQuery sync bridge
- RAGSearchResult: wraps rac_search_result_t with init(from:) bridge
- RAGResult: wraps rac_rag_result_t with init(from:) bridge
- All types conform to Sendable
- C string lifetime managed via nested withCString closures

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(01-02): create RunAnywhere+RAG.swift public API and RAGEvents.swift

- RunAnywhere+RAG: ragCreatePipeline, ragDestroyPipeline, ragIngest,
  ragClearDocuments, ragDocumentCount, ragQuery as public static API
- RAGEvents: ingestionStarted, ingestionComplete, queryStarted,
  queryComplete, pipelineCreated, pipelineDestroyed, error factory methods
- All RAG events published to EventBus.shared with category .rag
- CppBridge.RAG: added createPipeline(swiftConfig:) and query(swiftOptions:)
  overloads to contain C string pointer lifetimes within actor methods

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(02-01): create DocumentService for PDF and JSON text extraction

- Add DocumentType enum (pdf/json/unsupported) derived from file extension
- Add DocumentServiceError with descriptive LocalizedError messages
- Implement DocumentService.extractText(from:) for PDF via PDFKit and JSON via JSONSerialization
- Handle security-scoped resource access for document picker URLs
- Recursively extract all string values from nested JSON structures

* feat(02-01): create RAGViewModel for document lifecycle and query orchestration

- Add MessageRole enum (user/assistant/system)
- Add RAGViewModel @mainactor @observable with document and query state
- Implement loadDocument(url:config:) for extraction + pipeline creation + ingestion
- Implement askQuestion() for RAG query with conversation history
- Implement clearDocument() to destroy pipeline and reset all state
- Wire RunAnywhere.ragIngest and RunAnywhere.ragQuery SDK calls
- Persistent isDocumentLoaded state across multiple askQuestion calls

* feat(02-02): create DocumentRAGView with document picker and Q&A interface

- SwiftUI view binding to RAGViewModel via @State
- fileImporter modifier for PDF and JSON document selection
- Document status bar (no-doc / loading / loaded states)
- Inline error banner with dismiss action
- ScrollViewReader message list with auto-scroll on new messages
- Input bar with disabled state when no document loaded or querying
- RAGMessageBubble with user/assistant alignment using AppColors
- ragConfig placeholder with empty model paths (wired in future iteration)

* feat(02-02): wire DocumentRAGView into ContentView MoreHubView

- Add NavigationLink to DocumentRAGView as first item in MoreHubView
- Use doc.text.magnifyingglass SF Symbol with indigo color
- Placed before existing Transcribe/Speak/Storage links
- RAG feature now accessible from More tab navigation

* fix(ios-rag): add model selection UI for embedding and LLM models

Root cause: DocumentRAGView used empty placeholder strings for embeddingModelPath and llmModelPath in RAGConfiguration, causing pipeline creation to fail with error -102 (notInitialized).

- Add .ragEmbedding and .ragLLM cases to ModelSelectionContext, with framework-level filtering (ONNX for embedding, llamaCpp for LLM)
- Add allowedFrameworks property to ModelSelectionContext for precise framework filtering
- Update ModelSelectionSheet to filter by allowedFrameworks and skip memory-loading for RAG contexts
- Rewrite DocumentRAGView to track selectedEmbeddingModel and selectedLLMModel, show model picker rows, compute RAGConfiguration from real localPaths, and gate document selection on both models being ready

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(ios-rag): add embedding model support for RAG pipeline

Root cause: Three issues prevented embedding models from appearing
and downloading in the iOS app RAG feature:

1. ModelCategory enum was missing .embedding case (C layer had
   RAC_MODEL_CATEGORY_EMBEDDING = 7 but Swift enum didn't expose it).
   Added .embedding to ModelTypes.swift and updated C bridge
   conversions in ModelTypes+CppBridge.swift and CppBridge+ModelAssignment.swift.

2. No ONNX embedding models registered in RunAnywhereAIApp.swift.
   Added all-MiniLM-L6-v2 (model.onnx) and its vocab file, matching
   the React Native example app.

3. ModelSelectionSheet .ragEmbedding context was filtering by
   [.language] instead of [.embedding]. Updated to use the correct
   category. Also excluded vocab/tokenizer files from the picker
   so users only see selectable embedding models.

4. DocumentRAGView now resolves vocab path and passes it as
   embeddingConfigJSON to RAGConfiguration, matching the React
   Native RAGScreen pattern.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* RAG code swift

* build scripts +package.swift

* Addressed the bot issues + removed accidental docs

* docs(01-01): complete RAG C API bridge plan - add SUMMARY, update STATE, ROADMAP, REQUIREMENTS

- 01-01-SUMMARY.md: documents what was built, decisions, and deviations
- STATE.md: advance to plan 1 complete, add 3 architectural decisions
- ROADMAP.md: mark 01-01-PLAN.md complete, progress 1/2 in Phase 1
- REQUIREMENTS.md: mark SDK-01 complete

* docs(01-02): complete RAG public API plan - add SUMMARY, update STATE, ROADMAP, REQUIREMENTS

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(02): create phase plan for iOS app RAG feature

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs(02-01): complete iOS app RAG data/logic layer plan - add SUMMARY, update STATE, ROADMAP, REQUIREMENTS

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(02-02): complete RAG UI plan - add SUMMARY, update STATE, ROADMAP

- 02-02-SUMMARY.md: DocumentRAGView + ContentView wiring complete
- STATE.md: Phase 2 complete (2/2 plans), progress 100%
- ROADMAP.md: Phase 2 marked complete with 2 summaries

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Kotlin-RAG

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: remove planning directory from Kotlin branch

* KOTLIN-RAG

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Made this pathfinding consistent with the other modules

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Reduce the cosine similarity values so that you get results.

---------

Co-authored-by: Hsin-Wen Chang <bow1226@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

.gitignore

@@ -192,6 +192,12 @@ lint/reports/
 *.rar
 hs_err_pid*
 
+# Node.js / NPM / Yarn
+node_modules/
+.npm
+.yarn/cache
+.yarn/install-state.gz
+
 # Flutter/Dart
 .dart_tool/
 .flutter-plugins
@@ -378,6 +384,8 @@ sdk/runanywhere-flutter/android/*.aar
 
 # React Native - Pre-built xcframeworks (build artifacts)
 sdk/runanywhere-react-native/packages/*/ios/xcframeworks/
+tools/
+sdk/runanywhere-react-native/packages/rag/ios/.testlocal
 
 
 # Node

.npmrc

@@ -0,0 +1,32 @@
+# pnpm configuration for RunAnywhere monorepo
+
+# Use node-modules linker for better React Native compatibility
+node-linker=node-modules
+
+# Hoist all dependencies to root node_modules for consistency
+shamefully-hoist=true
+
+# Don't fail on missing peer dependencies
+strict-peer-dependencies=false
+
+# Use all available cores for faster installation
+prefer-offline=false
+
+# Verify package integrity
+verify-store-integrity=true
+
+# Use lockfile for reproducible installs
+lockfile=true
+
+# Depth for module hoisting
+hoist-pattern[]=*
+hoist-pattern[]=*/**
+
+# Store location (default is fine)
+# store-dir=.pnpm-store
+
+# For CI/CD environments
+# ci-mode=true
+
+# For development - allow same version installs
+# save-exact=false

.yarnrc.yml

@@ -43,6 +43,12 @@ let useLocalBinaries = true //  Toggle: true for local dev, false for release
 // Updated automatically by CI/CD during releases
 let sdkVersion = "0.19.1"
 
+// RAG binary is only available in local dev mode until the release artifact is published.
+// In remote mode, the RAG xcframework zip + checksum don't exist yet, so including the
+// binary target would block ALL SPM package resolution (not just RAG).
+// Set to true once RABackendRAG-v<version>.zip is published to GitHub releases.
+let ragRemoteBinaryAvailable = false
+
 let package = Package(
     name: "runanywhere-sdks",
     platforms: [
@@ -73,7 +79,8 @@ let package = Package(
             name: "RunAnywhereLlamaCPP",
             targets: ["LlamaCPPRuntime"]
         ),
-    ],
+
+    ] + ragProducts(),
     dependencies: [
         .package(url: "https://github.com/apple/swift-crypto.git", from: "3.0.0"),
         .package(url: "https://github.com/Alamofire/Alamofire.git", from: "5.9.0"),
@@ -111,7 +118,7 @@ let package = Package(
         // =================================================================
         .target(
             name: "ONNXBackend",
-            dependencies: ["RABackendONNXBinary", "ONNXRuntimeBinary"],
+            dependencies: ["RABackendONNXBinary"],
             path: "sdk/runanywhere-swift/Sources/ONNXRuntime/include",
             publicHeadersPath: "."
         ),
@@ -132,7 +139,7 @@ let package = Package(
                 .product(name: "StableDiffusion", package: "ml-stable-diffusion"),
                 "CRACommons",
                 "RACommonsBinary",
-            ],
+            ] + ragCoreDependencies(),
             path: "sdk/runanywhere-swift/Sources/RunAnywhere",
             exclude: ["CRACommons"],
             swiftSettings: [
@@ -194,9 +201,61 @@ let package = Package(
             path: "sdk/runanywhere-swift/Tests/RunAnywhereTests"
         ),
 
-    ] + binaryTargets()
+    ] + ragTargets() + binaryTargets()
 )
 
+// =============================================================================
+// RAG TARGET HELPERS
+// =============================================================================
+// RAG targets are gated because the remote binary artifact doesn't exist yet.
+// Including a binary target with a placeholder checksum blocks ALL SPM resolution.
+
+/// RAG product (library) — only included when the binary is available
+func ragProducts() -> [Product] {
+    guard useLocalBinaries || ragRemoteBinaryAvailable else { return [] }
+    return [
+        .library(
+            name: "RunAnywhereRAG",
+            targets: ["RAGRuntime"]
+        ),
+    ]
+}
+
+/// RAG dependency for the RunAnywhere core target
+func ragCoreDependencies() -> [Target.Dependency] {
+    guard useLocalBinaries || ragRemoteBinaryAvailable else { return [] }
+    return [
+        "RAGBackend",
+    ]
+}
+
+/// RAG-related targets (C bridge + Swift runtime)
+func ragTargets() -> [Target] {
+    guard useLocalBinaries || ragRemoteBinaryAvailable else { return [] }
+    return [
+        // C Bridge Module - RAG Backend Headers
+        .target(
+            name: "RAGBackend",
+            dependencies: ["RABackendRAGBinary"],
+            path: "sdk/runanywhere-swift/Sources/RAGRuntime/include",
+            publicHeadersPath: "."
+        ),
+        // RAG Runtime Backend
+        .target(
+            name: "RAGRuntime",
+            dependencies: [
+                "RunAnywhere",
+                "RAGBackend",
+            ],
+            path: "sdk/runanywhere-swift/Sources/RAGRuntime",
+            exclude: ["include"],
+            linkerSettings: [
+                .linkedLibrary("c++"),
+            ]
+        ),
+    ]
+}
+
 // =============================================================================
 // BINARY TARGET SELECTION
 // =============================================================================
@@ -224,16 +283,20 @@ func binaryTargets() -> [Target] {
                 name: "RABackendONNXBinary",
                 path: "sdk/runanywhere-swift/Binaries/RABackendONNX.xcframework"
             ),
+            .binaryTarget(
+                name: "RABackendRAGBinary",
+                path: "sdk/runanywhere-swift/Binaries/RABackendRAG.xcframework"
+            ),
         ]
 
         // Local combined ONNX Runtime xcframework (iOS + macOS)
         // Created by: cd sdk/runanywhere-swift && ./scripts/create-onnxruntime-xcframework.sh
-        targets.append(
-            .binaryTarget(
-                name: "ONNXRuntimeBinary",
-                path: "sdk/runanywhere-swift/Binaries/onnxruntime.xcframework"
-            )
-        )
+        // targets.append(
+        //     .binaryTarget(
+        //         name: "ONNXRuntimeBinary",
+        //         path: "sdk/runanywhere-swift/Binaries/onnxruntime.xcframework"
+        //     )
+        // )
 
         return targets
     } else {
@@ -242,7 +305,7 @@ func binaryTargets() -> [Target] {
         // Download XCFrameworks from GitHub releases
         // All xcframeworks include iOS + macOS slices (v0.19.0+)
         // =====================================================================
-        return [
+        var targets: [Target] = [
             .binaryTarget(
                 name: "RACommonsBinary",
                 url: "https://github.com/RunanywhereAI/runanywhere-sdks/releases/download/v\(sdkVersion)/RACommons-v\(sdkVersion).zip",
@@ -264,5 +327,18 @@ func binaryTargets() -> [Target] {
                 checksum: "e0180262bd1b10fcda95aaf9aac595af5e6819bd454312b6fc8ffc3828db239f"
             ),
         ]
+
+        // Only include RAG binary when the release artifact is available
+        if ragRemoteBinaryAvailable {
+            targets.append(
+                .binaryTarget(
+                    name: "RABackendRAGBinary",
+                    url: "https://github.com/RunanywhereAI/runanywhere-sdks/releases/download/v\(sdkVersion)/RABackendRAG-v\(sdkVersion).zip",
+                    checksum: "0000000000000000000000000000000000000000000000000000000000000000" // Replace with actual checksum
+                )
+            )
+        }
+
+        return targets
     }
-}
+}