llama-cpp-pro 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,295 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- **Package rename:** npm package and GitHub repository are now **`llama-cpp-pro`** (formerly `llama-cpp-capacitor` / `annadata-llama-cpp`). Install with `npm install llama-cpp-pro`. Existing `llama-cpp-capacitor` publishes on npm remain available.
+
+## [0.2.1] - 2025-07-07
+
+### Added
+- **Full cross-platform gap closure** — All 47 methods in `LlamaCppPlugin` are now fully implemented on iOS, Android, Web/PWA, and Desktop. Zero stubs remain.
+- **iOS — Session management** (`loadSession`/`saveSession`): Wired to `llama_load_session_file` / `llama_save_session_file` via new `LlamaNativeBridge` symbols. KV-cache state is correctly persisted and restored.
+- **iOS — LoRA adapters** (`applyLoraAdapters`, `removeLoraAdapters`, `getLoadedLoraAdapters`): Now call `llama_apply_lora_adapters`, `llama_remove_lora_adapters`, `llama_get_loaded_lora_adapters` via `dlsym`.
+- **iOS — Multimodal** (`initMultimodal`, `isMultimodalEnabled`, `getMultimodalSupport`, `releaseMultimodal`): Wired to `llama_init_multimodal`, `llama_is_multimodal_enabled`, `llama_get_multimodal_support`, `llama_release_multimodal`.
+- **iOS — TTS/Vocoder** (all 6 methods): Wired to `llama_init_vocoder`, `llama_get_formatted_audio_completion`, `llama_get_audio_completion_guide_tokens`, `llama_decode_audio_tokens`, `llama_release_vocoder`.
+- **iOS — Rerank**: Replaced empty-array stub with real `llama_rerank_json` → `completion::rerank()` call.
+- **iOS — Bench**: Replaced `"[]"` stub with real `llama_bench` → `completion::bench()` call.
+- **iOS — GPU reporting**: `initContext` now queries `llama_get_context_gpu_info` and surfaces actual Metal usage in the `gpu` / `reasonNoGPU` fields.
+- **iOS — Download management**: Replaced blocking `Data(contentsOf:)` with `URLSession` + `URLSessionDownloadDelegate` for real streaming progress tracking and cancellable downloads.
+- **Android — LoRA adapters**: Java `applyLoraAdapters`, `removeLoraAdapters`, `getLoadedLoraAdapters` now call their JNI counterparts in `jni-lora.cpp` (was no-op).
+- **Android — Multimodal**: Java `initMultimodal`, `isMultimodalEnabled`, `getMultimodalSupport`, `releaseMultimodal` now call through to `jni-multimodal.cpp` (was flag-only).
+- **Android — TTS/Vocoder**: Java `initVocoder`, `getFormattedAudioCompletion`, `getAudioCompletionGuideTokens`, `decodeAudioTokens`, `releaseVocoder` now call through to `jni-tts.cpp` (was flag-only).
+- **Android — Session management**: Java `loadSession`/`saveSession` now call `loadSessionNative`/`saveSessionNative` backed by `llama_state_load_file` / `llama_state_save_file`.
+- **Android — Rerank**: Replaced `Math.random()` mock with real `rerankNative` JNI call backed by `completion::rerank()`.
+- **Android — Bench**: Replaced `"[]"` stub with `benchNative` → `completion::bench()`.
+- **Android — Completion param propagation**: All 20+ sampling parameters now extracted from `JSObject` and forwarded to `common_params::sampling` (previously only `temperature`, `n_predict`, `prompt`).
+- **Android — GPU reporting**: `initContext` now queries `modelInfoNative` and reflects actual Vulkan/GPU availability.
+- **Web — `getFormattedChat`**: Delegates to `provider.getFormattedChat` when available (WASM Jinja path), with 4-template client-side fallback.
+- **Web — `chat()`**: Now uses `getFormattedChat` internally for proper template formatting instead of naive role-prefix concatenation.
+- **Web — Completion params**: All sampling parameters forwarded to provider (`top_p`, `top_k`, `min_p`, `repeat_penalty`, `seed`, `stop`, `grammar`).
+- **C++ — New public ABI symbols** in `cap-ios-bridge.h`/`cap-ios-bridge.cpp`: `llama_rerank_json`, `llama_bench`, `llama_load_session_file`, `llama_save_session_file`, `llama_apply_lora_adapters`, `llama_remove_lora_adapters`, `llama_get_loaded_lora_adapters`, `llama_init_multimodal`, `llama_is_multimodal_enabled`, `llama_get_multimodal_support`, `llama_release_multimodal`, `llama_init_vocoder`, `llama_is_vocoder_enabled`, `llama_get_formatted_audio_completion`, `llama_get_audio_completion_guide_tokens`, `llama_decode_audio_tokens`, `llama_release_vocoder`, `llama_get_context_gpu_info`.
+- **Documentation — Feature Coverage Matrix**: Added full 47-method cross-platform matrix to `README.md`.
+- **Documentation — Build guides**: `README_BUILD_SYSTEM.md` and `BUILD_GUIDE.md` updated to cover iOS, Android, Web/PWA, and Desktop with step-by-step instructions for all platforms.
+
+### Fixed
+- **Android `rerank`**: Was returning random scores (`Math.random()`) — now correctly calls native reranking.
+- **iOS/Android `bench`**: Was returning empty `"[]"` — now returns real pp/tg performance data.
+- **iOS/Android `loadSession`/`saveSession`**: Was returning hardcoded zeros — now persists/restores actual KV-cache state.
+- **iOS/Android LoRA**: Was silently succeeding with no effect — now applies/removes adapters natively.
+- **iOS/Android Multimodal `getMultimodalSupport`**: Was hardcoded `{vision:true, audio:true}` — now queries actual model capabilities.
+- **iOS/Android TTS**: All vocoder methods were stubs — now fully operational.
+- **Android completion `stop` array**: Was silently ignored — now parsed and forwarded as `antiprompt` to llama.cpp.
+
+
+
+### Changed
+- **App store size**: Build only **arm64-v8a** for Android (drop armeabi-v7a); strip iOS framework and Android `.so` debug symbols. See `APP_STORE_SIZE.md`.
+- **Package**: Exclude `ios/Tests` from published `files`; `build-native.sh` builds Android arm64-only and strips binaries.
+
+### Added
+- **APP_STORE_SIZE.md**: Guide on what affects app size, what can be removed, and store-size optimizations.
+
+## [0.1.0] - 2025-01-23
+
+### Added
+- **Complete iOS support**: Full native iOS build and packaging
+  - ARM64 framework (`llama-cpp.framework`) with Metal acceleration
+  - Automated copy to `ios/Frameworks/` for npm package
+  - CocoaPods `vendored_frameworks` in `LlamaCpp.podspec`
+- **Unified build**: `build-native.sh` builds both iOS and Android; single workflow for publishing
+
+### Changed
+- **Android**: NDK detection uses versioned path (`ndk/<version>/`); build limited to arm64-v8a and armeabi-v7a (x86/x86_64 require separate CMake setup)
+- **Android JNI**: `n_threads` via `cpuparams`, `llama_batch_add` as `capllama::llama_batch_add`; embedding fixes
+- **NEON**: Guarded `vcvtnq_s32_f32` fallback for Clang/NDK to avoid redefinition with `arm_neon.h`
+
+### Technical
+- `package.json`: version 0.1.0; `ios/Frameworks` in `files`; keywords `ios`, `android`
+- `PUBLISH_GUIDE.md`: Steps for building and publishing iOS + Android npm package
+
+## [0.0.13] - 2025-08-30
+
+### Fixed
+- **Segmentation Fault Protection**: Added signal handlers to catch and handle segmentation faults during model loading
+- **Enhanced Model Compatibility**: Added GGUF version checking and ultra-minimal parameter fallback
+- **Memory Safety**: Disabled potentially problematic features (mmap, quantized matrix multiplication) in fallback mode
+- **Crash Prevention**: Implemented multiple layers of protection against model loading crashes
+
+### Technical
+- Added signal handlers for SIGSEGV to prevent app crashes during model loading
+- Enhanced model validation with GGUF version checking
+- Implemented ultra-minimal parameter set with disabled mmap and quantized operations
+- Added comprehensive error messages for model corruption and compatibility issues
+- Improved memory safety by disabling potentially problematic llama.cpp features
+
+## [0.0.12] - 2025-08-30
+
+### Fixed
+- **Enhanced File Path Resolution**: Added comprehensive path checking for model files across multiple Android directories
+- **Improved Model Validation**: Enhanced file validation with better error handling and logging
+- **Better Error Messages**: More descriptive error messages to help diagnose model loading issues
+- **Robust File Detection**: Added automatic detection of model files in common Android storage locations
+
+### Technical
+- Added multiple path checking for model files (app files, Documents, external storage)
+- Enhanced file validation with size and GGUF format checking
+- Improved logging to show all checked paths and file status
+- Better error handling with fallback to minimal parameters
+- Added comprehensive path resolution for Android file system
+
+## [0.0.11] - 2025-08-30
+
+### Fixed
+- **Model Validation**: Added comprehensive model file validation before loading
+- **Crash Prevention**: Enhanced error handling to prevent crashes during model loading
+- **GGUF Format Check**: Added validation to ensure the model file is a valid GGUF format
+- **Exception Handling**: Added try-catch blocks around model loading operations
+
+### Technical
+- Added file existence and size validation before model loading
+- Added GGUF magic number validation to ensure proper file format
+- Enhanced exception handling with detailed error messages
+- Added comprehensive logging for model validation steps
+- Improved error messages to help diagnose model compatibility issues
+
+## [0.0.10] - 2025-08-30
+
+### Fixed
+- **Model Loading Issues**: Enhanced model loading with better error handling and fallback parameters
+- **Common Parameters**: Added comprehensive common_params initialization for proper model loading
+- **Debug Logging**: Added detailed logging for model loading process to help diagnose issues
+
+### Technical
+- Added fallback to minimal parameters if standard parameters fail
+- Enhanced error logging to show model path and parameters being used
+- Added comprehensive common_params initialization with all required fields
+- Improved model loading reliability with multiple parameter sets
+
+## [0.0.9] - 2025-08-30
+
+### Fixed
+- **JNI Function Naming**: Fixed JNI function names to match Java native method declarations
+- **UnsatisfiedLinkError**: Resolved "No implementation found" errors for native methods
+- **Function Signature Mismatch**: Corrected JNI function signatures to match Java expectations
+
+### Technical
+- Renamed all JNI functions to include "Native" suffix to match Java declarations
+- Removed duplicate wrapper functions that were causing conflicts
+- Fixed function signatures (e.g., completionNative no longer expects params parameter)
+- All native methods now properly link between Java and C++
+
+## [0.0.8] - 2025-08-30
+
+### Fixed
+- **Android Native Library Naming**: Fixed library naming to use `libllama-cpp.so` instead of architecture-specific names
+- **Java Library Loading**: Updated CMakeLists.txt to build libraries with generic names for Java compatibility
+- **System.loadLibrary() Compatibility**: Java code can now properly load the native library
+
+### Technical
+- Changed library target names from `llama-cpp-arm64-v8a` to `llama-cpp` in CMakeLists.txt
+- Updated all architecture-specific build configurations to use the same library name
+- This ensures `System.loadLibrary("llama-cpp")` can find the correct library file
+
+## [0.0.7] - 2025-08-30
+
+### Fixed
+- **Missing CPP Directory**: Added `cpp/` directory to npm package files to fix CMake build errors
+- **NPM Package Issue**: The cpp directory containing llama.cpp source files was not included in the published package
+- **CMake Build Failure**: Fixed "Cannot find source file" errors when installing plugin as npm dependency
+
+### Technical
+- Updated package.json files array to include cpp directory
+- This ensures all necessary source files are available when the plugin is installed as a dependency
+- CMake build system can now properly locate and compile llama.cpp source files
+
+## [0.0.6] - 2025-08-30
+
+### Fixed
+- **CMake Path Issue**: Fixed incorrect relative path in CMakeLists.txt that was causing "Cannot find source file" errors
+- **Android Build Success**: Resolved CMake configuration issue and successfully built native library
+- **Path Resolution**: Corrected `LLAMACPP_LIB_DIR` from `../../cpp` to `../../../cpp` for proper source file location
+
+### Technical
+- Android native library now compiles successfully with correct file paths
+- CMake build system properly locates all llama.cpp source files
+- Ready for real model inference instead of placeholder responses
+
+## [0.0.5] - 2025-08-30
+
+### Fixed
+- **ANDROID BUILD SUCCESS**: Fixed all compilation errors and successfully built native library
+- Fixed JNI type declarations with proper namespace qualifiers (`rnllama::`)
+- Added missing `llama_model_saver.cpp` to CMakeLists.txt
+- Fixed CMake configuration to use generic implementation for all architectures
+- Added missing `rnllama_verbose` symbol to JNI implementation
+- Simplified build to focus on ARM64 architecture (most common for modern Android)
+- Removed problematic CMake dependency that was causing build failures
+
+### Technical
+- Android native library now compiles successfully with all llama.cpp components
+- JNI bridge properly connects Java plugin to C++ llama.cpp library
+- Native context management and model loading implemented
+- Ready for real model inference instead of placeholder responses
+
+## [0.0.4] - 2025-08-30
+
+### Fixed
+- **REAL LLAMA.CPP INTEGRATION**: Replaced placeholder implementations with actual llama.cpp library calls
+- Fixed Android JNI implementation to use real llama.cpp functions instead of sample text
+- Updated completion method to perform actual text generation using the loaded model
+- Fixed getFormattedChat to use native llama.cpp chat formatting
+- Added proper native context management with real model loading
+- Fixed type conversion issues in parameter extraction
+
+### Technical
+- Implemented proper JNI bridge between Java and C++ llama.cpp library
+- Added native method declarations for all core functions
+- Fixed JSObject parameter extraction with proper type casting
+- Added native context ID tracking for proper resource management
+- Integrated real tokenization and completion pipeline
+
+## [0.0.3] - 2025-08-30
+
+### Fixed
+- Fixed Android compilation errors in LlamaCppPlugin.java
+- Corrected JSArray method calls with proper exception handling
+- Fixed saveSession method signature mismatch
+- Added proper JSONException handling for all JSArray operations
+- Resolved type conversion issues between Map<String,Object> and JSObject
+
+### Technical
+- Added try-catch blocks for all JSArray.getString() and JSArray.getInt() calls
+- Fixed method parameter mismatches in Android implementation
+- Improved error handling and type safety in Android plugin
+
+## [0.0.2] - 2025-08-30
+
+### Added
+- Comprehensive API documentation (API_DOCUMENTATION.md)
+- Quick reference guide (QUICK_REFERENCE.md)
+- Complete TypeScript declarations (types/llama-cpp-pro.d.ts)
+- Fixed build warnings and improved TypeScript configuration
+- Enhanced IDE support with IntelliSense
+
+### Documentation
+- Complete API reference with examples
+- Platform support matrix
+- Performance tips and troubleshooting guide
+- TypeScript type safety improvements
+
+## [0.0.1] - 2025-08-29
+
+### Added
+- Initial release of CapacitorJS plugin for llama.cpp
+- Complete native iOS implementation with Swift and C++ integration
+- Complete native Android implementation with Java and JNI
+- Web fallback implementation for unsupported features
+- Comprehensive TypeScript definitions and interfaces
+- Support for text completion (basic and streaming)
+- Chat conversation functionality with message formatting
+- Tokenization and detokenization
+- Embeddings generation
+- Session management (save/load conversation states)
+- Multimodal support for image processing
+- Text-to-Speech (TTS) with vocoder models
+- LoRA adapters support (apply, remove, list)
+- Performance benchmarking capabilities
+- Structured output with JSON Schema support
+- Error handling and result types
+- Integration testing framework with Jest and custom test runner
+- Build automation scripts for native compilation
+- Comprehensive documentation (README, TESTING, CONTRIBUTING)
+
+### Technical Features
+- Native C++ integration using dlopen/dlsym on iOS
+- JNI bridge implementation for Android
+- CMake build system for cross-platform compilation
+- Event-driven architecture with Capacitor listeners
+- Memory management and context handling
+- Cross-platform compatibility (iOS, Android, Web)
+
+### Documentation
+- Complete API reference
+- Installation and setup instructions
+- Usage examples and code samples
+- Integration testing guide
+- Platform-specific build instructions
+- Troubleshooting guide
+
+## [Unreleased]
+
+### Planned
+- Support for larger models (13B, 70B)
+- Enhanced multimodal capabilities
+- Real-time audio processing
+- Advanced LoRA fine-tuning
+- Model quantization optimization
+- Performance monitoring and analytics
+- Cloud model integration
+- Advanced caching mechanisms

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yakub Mohammad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LlamaCpp.podspec

@@ -0,0 +1,33 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'LlamaCpp'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  
+  # Swift implementation
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '14.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+  
+  # Include the pre-built native llama-cpp framework
+  # Built with: ./build-variants.sh --variant minimal (or core/development)
+  # Framework includes arm64 architecture with debug symbols stripped
+  # For building locally, see BUILD_GUIDE.md
+  s.vendored_frameworks = 'ios/Frameworks/llama-cpp.framework'
+  s.pod_target_xcconfig = {
+    'FRAMEWORK_SEARCH_PATHS' => '$(inherited) "$(PODS_TARGET_SRCROOT)/ios/Frameworks"'
+  }
+  
+  # Required for proper framework linking
+  s.user_target_xcconfig = {
+    'FRAMEWORK_SEARCH_PATHS' => '$(inherited) "$(PODS_TARGET_SRCROOT)/ios/Frameworks"'
+  }
+end

package/LlamaCppCapacitor.podspec

@@ -0,0 +1,33 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'LlamaCppCapacitor'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  
+  # Swift implementation
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+  
+  # Include the pre-built native llama-cpp framework
+  # Built with: ./build-variants.sh --variant minimal (or core/development)
+  # Framework includes arm64 architecture with debug symbols stripped
+  # For building locally, see BUILD_GUIDE.md
+  s.vendored_frameworks = 'ios/Frameworks/llama-cpp.framework'
+  s.pod_target_xcconfig = {
+    'FRAMEWORK_SEARCH_PATHS' => '$(inherited) "$(PODS_TARGET_SRCROOT)/ios/Frameworks"'
+  }
+  
+  # Required for proper framework linking
+  s.user_target_xcconfig = {
+    'FRAMEWORK_SEARCH_PATHS' => '$(inherited) "$(PODS_TARGET_SRCROOT)/ios/Frameworks"'
+  }
+end

package/Package.swift

@@ -0,0 +1,29 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "LlamaCppCapacitor",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "LlamaCppCapacitor",
+            targets: ["LlamaCppCapacitor"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "LlamaCppCapacitor",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+            ],
+            path: "ios/Sources/LlamaCppCapacitor",
+            linkerSettings: [
+                .linkedLibrary("c++"),
+                .linkedFramework("Accelerate")
+            ]
+        )
+    ]
+)

package/README.md

@@ -0,0 +1,93 @@
+# llama-cpp-pro
+
+[Actions Status](https://github.com/arusatech/llama-cpp-pro/actions)
+[License: MIT](https://opensource.org/licenses/MIT)
+[npm](https://www.npmjs.com/package/llama-cpp-pro/)
+[Support: ANNADATA.AI](https://annadata.ai/)
+[Principal Engineer / Architect: Mr. Yakub Mohammad](https://annadata.ai/)
+
+A native Capacitor plugin that embeds [llama.cpp](https://github.com/ggerganov/llama.cpp) directly into mobile apps, enabling offline AI inference with comprehensive support for text generation, multimodal processing, TTS, LoRA adapters, and more.
+
+[Annadata.ai](https://annadata.ai): Inference of [LLaMA](https://arxiv.org/abs/2302.13971) model in pure C/C++ used in [Annadata.ai](https://annadata.ai)
+
+## 🚀 Features
+
+- **Offline AI Inference**: Run large language models completely offline on mobile devices
+- **Text Generation**: Complete text completion with streaming support
+- **Chat Conversations**: Multi-turn conversations with context management
+- **Multimodal Support**: Process images and audio alongside text
+- **Text-to-Speech (TTS)**: Generate speech from text using vocoder models
+- **LoRA Adapters**: Fine-tune models with LoRA adapters
+- **Embeddings**: Generate vector embeddings for semantic search
+- **Reranking**: Rank documents by relevance to queries
+- **Session Management**: Save and load conversation states
+- **Benchmarking**: Performance testing and optimization tools
+- **Structured Output**: Generate JSON with schema validation
+- **Cross-Platform**: iOS, Android, **Web/PWA**, and **Desktop** (Windows, macOS, Linux) with native optimizations
+
+
+
+## 📱 Platform Support
+
+
+| Feature            | iOS   | Android    | Web (PWA) | Desktop                |
+| ------------------ | ----- | ---------- | --------- | ---------------------- |
+| Text Generation    | ✅     | ✅          | ✅         | ✅                      |
+| Chat Conversations | ✅     | ✅          | ✅         | ✅                      |
+| Streaming          | ✅     | ✅          | ✅         | ✅¹                     |
+| Multimodal         | ✅     | ✅          | ✅²        | ✅                      |
+| TTS                | ✅     | ✅          | ✅²        | ✅                      |
+| LoRA Adapters      | ✅     | ✅          | ✅²        | ✅                      |
+| Embeddings         | ✅     | ✅          | ✅         | ✅                      |
+| Reranking          | ✅     | ✅          | ✅³        | ✅                      |
+| Session Management | ✅     | ✅          | ✅⁴        | ✅                      |
+| Benchmarking       | ✅     | ✅          | ✅         | ✅                      |
+| GPU Acceleration   | Metal | CPU/Adreno | —         | Vulkan/CUDA/ROCm/Metal |
+
+
+¹ **Desktop:** SSE streaming from the native sidecar (`/v1/chat/completions`, `/v1/completions` with `stream: true`).  
+² **Web:** auxiliary GGUF files must be staged in WASM VFS.  
+³ **Web:** requires rank-pooling embedding model.  
+⁴ **Web:** sessions persist in worker MEMFS for tab lifetime.
+
+---
+
+## Builds
+
+```bash
+# iOS + Android + PWA (npm release / Capacitor)
+./build-variants.sh --variant minimal
+
+# iOS only / Android only
+./build-variants.sh --variant ios-only
+./build-variants.sh --variant android-only
+
+# Desktop / Electron (macOS universal sidecar: arm64 + x64)
+./build-variants.sh --variant desktop
+./build-variants.sh --variant minimal --with-desktop --desktop-arch=universal
+```
+
+See [BUILD_GUIDE.md](BUILD_GUIDE.md) and [README_BUILD_SYSTEM.md](README_BUILD_SYSTEM.md) for full build, API, and troubleshooting details.
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [llama.cpp](https://github.com/ggerganov/llama.cpp) - The core inference engine
+- [Capacitor](https://capacitorjs.com/) - The cross-platform runtime
+- [Annadata.ai](https://annadata.ai) - Complete system developed and powered by [npm](https://www.npmjs.com/package/llama-cpp-pro/)
+
+
+
+## 📞 Support
+
+- 📧 Email: [support@arusatech.com](mailto:support@arusatech.com) ; [yakub@annadata.ai](mailto:yakub@annadata.ai)
+- 🐛 Issues: [GitHub Issues](https://github.com/arusatech/llama-cpp-pro/issues)
+- 📖 Documentation: [GitHub Wiki](https://github.com/arusatech/llama-cpp-pro/wiki)
+

package/android/build.gradle

@@ -0,0 +1,88 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.2'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "ai.annadata.plugin.capacitor"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        
+        ndk {
+            abiFilters 'arm64-v8a'
+        }
+    }
+    
+    externalNativeBuild {
+        cmake {
+            path "src/main/CMakeLists.txt"
+            version "3.22.1"
+            // Explicitly set NDK version to avoid Windows dependencies
+            ndkVersion "29.0.13113456"
+        }
+    }
+    
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    
+    lintOptions {
+        abortOnError false
+    }
+    
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+    
+    sourceSets {
+        main {
+            java {
+                srcDirs = ['src/main/java']
+            }
+        }
+    }
+    
+    // Disable clean tasks that might cause issues
+    tasks.whenTaskAdded { task ->
+        if (task.name.contains('Clean') && task.name.contains('Debug')) {
+            task.enabled = false
+        }
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- Needed for binding a local TCP socket used by the in-process HTTP server -->
+    <uses-permission android:name="android.permission.INTERNET" />
+</manifest>