diff --git a/.gitignore b/.gitignore index 585b41e21..db4f4a996 100644 --- a/.gitignore +++ b/.gitignore @@ -1,41 +1,46 @@ -build* -.claude -.vscode -.DS_Store +**/build/ +*.a +*.so +*.dylib +*.bin *.gguf -weights/ -stage/ -.cache/ +*.npy +*.cg -android/libs/ -android/arm64-v8a/ -*.so +!cactus-engine/libs/curl/**/*.a +!android/mbedtls/**/*.a +apple/build-*/ apple/*.xcframework apple/libcactus*.a -*.a -!libs/curl/**/*.a -!cactus-engine/libs/curl/**/*.a -!android/mbedtls/**/*.a -venv +android/libcactus.so +android/libcactus.a +android/libs/ +android/arm64-v8a/ +bindings/flutter/libcactus.so +bindings/flutter/*.xcframework + +.claude +.vscode +.DS_Store __pycache__ *.egg-info -profile.txt -*_profile.txt -*.dylib -*.bin -tmp +venv -ruy -notes.txt +weights/ +stage/ +.cache/ +tmp site/ site_docs/ -*.npy +notes.txt +profile.txt +*_profile.txt tests/plan.md tests/assets/test_wav_info.txt vision_activations.json gemma-4-eap-extras/ .githooks/ -*.cg \ No newline at end of file +ruy diff --git a/README.md b/README.md index 0440e4b7e..5f98e25b0 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ A low-latency AI engine for mobile devices & wearables. Main features: - **Fast:** fastest inference on ARM CPU - **Low RAM:** zero-copy memory mapping ensures 10x lower RAM use than other engines -- **Multimodal:** one SDK for speech, vision, and language models +- **Multimodal:** one engine for speech, vision, and language models - **Cloud fallback:** automatically route requests to cloud models if needed - **Energy-efficient:** NPU-accelerated prefill @@ -116,18 +116,31 @@ void* output_data = graph.get_output(result); graph.hard_reset(); ``` -## API & SDK References +## APIs | Reference | Language | Description | |-----------|----------|-------------| -| [Engine API](docs/cactus_engine.md) | C | Chat completion, streaming, tool calling, transcription, embeddings, RAG, vision, VAD, vector index, cloud handoff | -| [Graph API](docs/cactus_graph.md) | C++ | Tensor operations, matrix multiplication, attention, normalization, activation functions | -| [Python SDK](/python/) | Python | Mac, Linux | -| [Swift SDK](/apple/) | Swift | iOS, macOS, tvOS, watchOS, Android | -| [Kotlin SDK](/android/) | Kotlin | Android, iOS (via KMP) | -| [Flutter SDK](/flutter/) | Dart | iOS, macOS, Android | -| [Rust SDK](/rust/) | Rust | Mac, Linux | -| [React Native](https://github.com/cactus-compute/cactus-react-native) | JavaScript | iOS, Android | +| Engine API | C | Chat completion, streaming, tool calling, transcription, embeddings, RAG, vision, VAD, vector index, cloud handoff | +| Graph API | C++ | Tensor operations, matrix multiplication, attention, normalization, activation functions | +| [Python Package](/python/) | Python | Python package and CLI | + +## Build + +```bash +cactus build --apple # iOS/macOS +cactus build --android # Android +cactus build --python # Python +cactus build # default static lib +``` + +## Bindings + +- [Swift](/bindings/swift/) +- [Kotlin](/bindings/kotlin/) +- [Flutter](/bindings/flutter/) +- [React Native](/bindings/react-native/) +- [Python](/bindings/python/) +- [Rust](/bindings/rust/) > **Model weights:** Pre-converted weights for all supported models at [huggingface.co/Cactus-Compute](https://huggingface.co/Cactus-Compute). @@ -266,7 +279,6 @@ graph.hard_reset(); │ cactus build build for ARM → build/libcactus.a │ │ --apple Apple (iOS/macOS) │ │ --android Android │ -│ --flutter Flutter (all platforms) │ │ --python shared lib for Python FFI │ │ │ │ cactus test run unit tests and benchmarks │ diff --git a/SECURITY.md b/SECURITY.md index 69bb17556..bb3ce4b31 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -21,7 +21,7 @@ We will acknowledge receipt within 48 hours and aim to provide a fix or mitigati ## Scope -This policy covers the Cactus inference engine, its SDKs (Python, Swift, Kotlin, Flutter, Rust, React Native), and the official model weights hosted on [HuggingFace](https://huggingface.co/Cactus-Compute). +This policy covers the Cactus inference engine, its bindings (Python, Swift, Kotlin, Flutter, Rust, React Native), and the official model weights hosted on [HuggingFace](https://huggingface.co/Cactus-Compute). ## Supported Versions diff --git a/android/CMakeLists.txt b/android/CMakeLists.txt index 13af640c3..79b424cab 100644 --- a/android/CMakeLists.txt +++ b/android/CMakeLists.txt @@ -1,202 +1,75 @@ cmake_minimum_required(VERSION 3.10) -project(Cactus LANGUAGES CXX) +project(CactusAndroid LANGUAGES CXX) set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_STANDARD_REQUIRED True) -set(CACTUS_REPO_ROOT "${CMAKE_SOURCE_DIR}/..") -set(CACTUS_ENGINE_DIR "${CACTUS_REPO_ROOT}/cactus-engine") -set(CACTUS_GRAPH_DIR "${CACTUS_REPO_ROOT}/cactus-graph") -set(CACTUS_KERNEL_DIR "${CACTUS_REPO_ROOT}/cactus-kernels") -set(CACTUS_CURL_ROOT "${CACTUS_ENGINE_DIR}/libs/curl" CACHE PATH "Path to vendored libcurl artifacts") - -set(_CACTUS_VERSION_FILE "${CACTUS_REPO_ROOT}/CACTUS_VERSION") -if(EXISTS "${_CACTUS_VERSION_FILE}") - file(READ "${_CACTUS_VERSION_FILE}" _CACTUS_VERSION_CONTENT) - string(STRIP "${_CACTUS_VERSION_CONTENT}" CACTUS_VERSION_STR) - message(STATUS "Cactus version: ${CACTUS_VERSION_STR}") -else() - set(CACTUS_VERSION_STR "") -endif() +set(PROJECT_ROOT "${CMAKE_SOURCE_DIR}/..") if(NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Release) - message(STATUS "CMAKE_BUILD_TYPE was not set, defaulting to Release.") endif() -file(GLOB KERNEL_SOURCES "${CACTUS_KERNEL_DIR}/src/*.cpp") -file(GLOB GRAPH_SOURCES "${CACTUS_GRAPH_DIR}/src/*.cpp") - -set(ENGINE_SOURCES - ${CACTUS_ENGINE_DIR}/src/bpe.cpp - ${CACTUS_ENGINE_DIR}/src/sp.cpp - ${CACTUS_ENGINE_DIR}/src/constraints.cpp - ${CACTUS_ENGINE_DIR}/src/model.cpp - ${CACTUS_ENGINE_DIR}/src/engine_image.cpp - ${CACTUS_ENGINE_DIR}/src/index.cpp - ${CACTUS_ENGINE_DIR}/src/index_ffi.cpp - ${CACTUS_ENGINE_DIR}/src/log.cpp - ${CACTUS_ENGINE_DIR}/src/graph_ffi.cpp - ${CACTUS_ENGINE_DIR}/src/rag.cpp - ${CACTUS_ENGINE_DIR}/src/telemetry.cpp - ${CACTUS_ENGINE_DIR}/src/telemetry_impl.cpp - ${CACTUS_ENGINE_DIR}/src/cloud.cpp - ${CACTUS_ENGINE_DIR}/src/init.cpp - ${CACTUS_ENGINE_DIR}/src/embed.cpp - ${CACTUS_ENGINE_DIR}/src/complete.cpp - ${CACTUS_ENGINE_DIR}/src/transcribe.cpp - ${CACTUS_ENGINE_DIR}/src/tokenizer.cpp - ${CACTUS_ENGINE_DIR}/src/npu.cpp -) - -set(HEADER_FILES - ${CACTUS_REPO_ROOT}/cactus/cactus.h - ${CACTUS_ENGINE_DIR}/cactus_engine.h - ${CACTUS_GRAPH_DIR}/cactus_graph.h - ${CACTUS_KERNEL_DIR}/cactus_kernels.h -) - -set(COMMON_SOURCES - ${KERNEL_SOURCES} - ${GRAPH_SOURCES} - ${ENGINE_SOURCES} -) - -if(NOT COMMON_SOURCES) - message(FATAL_ERROR "No source files found! Check repo layout under ${CACTUS_REPO_ROOT}") +if(NOT ${ANDROID_ABI} STREQUAL "arm64-v8a") + message(FATAL_ERROR "Unsupported Android ABI: ${ANDROID_ABI}. Cactus only supports arm64-v8a.") endif() -find_library(LOG_LIB log) - -add_library( - cactus - SHARED - ${COMMON_SOURCES} - ${CMAKE_SOURCE_DIR}/cactus_jni.cpp -) - -add_library( - cactus_static - STATIC - ${COMMON_SOURCES} -) - -set(COMMON_INCLUDE_DIRS - ${CACTUS_REPO_ROOT} - ${CACTUS_REPO_ROOT}/cactus - ${CACTUS_ENGINE_DIR} - ${CACTUS_ENGINE_DIR}/src - ${CACTUS_ENGINE_DIR}/libs - ${CACTUS_GRAPH_DIR} - ${CACTUS_GRAPH_DIR}/src - ${CACTUS_KERNEL_DIR} - ${CACTUS_KERNEL_DIR}/src - ${CACTUS_KERNEL_DIR}/libs -) - -target_include_directories(cactus PRIVATE ${COMMON_INCLUDE_DIRS}) -target_include_directories(cactus_static PRIVATE ${COMMON_INCLUDE_DIRS}) - -target_link_libraries(cactus ${LOG_LIB} android) - -set(CACTUS_CURL_INCLUDE_DIR "${CACTUS_CURL_ROOT}/include") -set(CACTUS_CURL_LIBRARY_ANDROID "${CACTUS_CURL_ROOT}/android/${ANDROID_ABI}/libcurl.a") set(CACTUS_MBEDTLS_ROOT "${CMAKE_SOURCE_DIR}/mbedtls/${ANDROID_ABI}") if(NOT EXISTS "${CACTUS_MBEDTLS_ROOT}") - set(CACTUS_MBEDTLS_ROOT "${CACTUS_REPO_ROOT}/libs/mbedtls/android/${ANDROID_ABI}") + set(CACTUS_MBEDTLS_ROOT "${PROJECT_ROOT}/libs/mbedtls/android/${ANDROID_ABI}") endif() -set(CACTUS_MBEDTLS_INCLUDE_DIR "${CACTUS_MBEDTLS_ROOT}/include") set(CACTUS_MBEDTLS_LIBRARY "${CACTUS_MBEDTLS_ROOT}/lib/libmbedtls.a") set(CACTUS_MBEDX509_LIBRARY "${CACTUS_MBEDTLS_ROOT}/lib/libmbedx509.a") set(CACTUS_MBEDCRYPTO_LIBRARY "${CACTUS_MBEDTLS_ROOT}/lib/libmbedcrypto.a") -if(EXISTS "${CACTUS_CURL_INCLUDE_DIR}/curl/curl.h" AND EXISTS "${CACTUS_CURL_LIBRARY_ANDROID}") - message(STATUS "Using vendored libcurl for Android: ${CACTUS_CURL_LIBRARY_ANDROID}") - if(NOT (EXISTS "${CACTUS_MBEDTLS_LIBRARY}" AND EXISTS "${CACTUS_MBEDX509_LIBRARY}" AND EXISTS "${CACTUS_MBEDCRYPTO_LIBRARY}")) - message(FATAL_ERROR "Vendored mbedTLS libraries not found. Expected: ${CACTUS_MBEDTLS_LIBRARY}, ${CACTUS_MBEDX509_LIBRARY}, ${CACTUS_MBEDCRYPTO_LIBRARY}") - endif() +set(CACTUS_ENGINE_DIR "${PROJECT_ROOT}/cactus-engine") +if(NOT TARGET cactus_engine) + add_subdirectory(${CACTUS_ENGINE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/cactus-engine) +endif() - target_include_directories(cactus PRIVATE "${CACTUS_CURL_INCLUDE_DIR}") - target_include_directories(cactus_static PRIVATE "${CACTUS_CURL_INCLUDE_DIR}") - target_include_directories(cactus PRIVATE "${CACTUS_MBEDTLS_INCLUDE_DIR}") - target_include_directories(cactus_static PRIVATE "${CACTUS_MBEDTLS_INCLUDE_DIR}") - target_compile_definitions(cactus PRIVATE CACTUS_USE_CURL=1) - target_compile_definitions(cactus_static PRIVATE CACTUS_USE_CURL=1) +find_library(LOG_LIB log) - target_link_libraries(cactus "${CACTUS_CURL_LIBRARY_ANDROID}") - target_link_libraries(cactus_static "${CACTUS_CURL_LIBRARY_ANDROID}") - target_link_libraries(cactus "${CACTUS_MBEDTLS_LIBRARY}" "${CACTUS_MBEDX509_LIBRARY}" "${CACTUS_MBEDCRYPTO_LIBRARY}") - target_link_libraries(cactus_static "${CACTUS_MBEDTLS_LIBRARY}" "${CACTUS_MBEDX509_LIBRARY}" "${CACTUS_MBEDCRYPTO_LIBRARY}") -else() - message(FATAL_ERROR "Vendored Android libcurl not found. Expected: ${CACTUS_CURL_INCLUDE_DIR}/curl/curl.h and ${CACTUS_CURL_LIBRARY_ANDROID}") +add_library(cactus SHARED ${CMAKE_SOURCE_DIR}/cactus_jni.cpp) +target_include_directories(cactus PRIVATE ${PROJECT_ROOT}/cactus ${CACTUS_ENGINE_DIR} ${CACTUS_ENGINE_DIR}/src) +target_link_libraries(cactus PRIVATE cactus_engine cactus_graph cactus_kernels) +target_link_libraries(cactus PRIVATE ${LOG_LIB} android) +if(EXISTS "${CACTUS_MBEDTLS_LIBRARY}" AND EXISTS "${CACTUS_MBEDX509_LIBRARY}" AND EXISTS "${CACTUS_MBEDCRYPTO_LIBRARY}") + target_link_libraries(cactus PRIVATE + "${CACTUS_MBEDTLS_LIBRARY}" + "${CACTUS_MBEDX509_LIBRARY}" + "${CACTUS_MBEDCRYPTO_LIBRARY}" + ) endif() +target_compile_definitions(cactus PRIVATE PLATFORM_CPU_ONLY=1) -set(COMMON_COMPILE_DEFINITIONS - PLATFORM_CPU_ONLY=1 -) -if(NOT "${CACTUS_VERSION_STR}" STREQUAL "") - list(APPEND COMMON_COMPILE_DEFINITIONS "CACTUS_COMPILE_TIME_VERSION=\"${CACTUS_VERSION_STR}\"") +set(_CACTUS_VERSION_FILE "${PROJECT_ROOT}/CACTUS_VERSION") +if(EXISTS "${_CACTUS_VERSION_FILE}") + file(READ "${_CACTUS_VERSION_FILE}" _CACTUS_VERSION_CONTENT) + string(STRIP "${_CACTUS_VERSION_CONTENT}" CACTUS_VERSION_STR) + target_compile_definitions(cactus PRIVATE CACTUS_COMPILE_TIME_VERSION="${CACTUS_VERSION_STR}") endif() -target_compile_definitions(cactus PRIVATE ${COMMON_COMPILE_DEFINITIONS}) -target_compile_definitions(cactus_static PRIVATE ${COMMON_COMPILE_DEFINITIONS}) - -set(COMMON_COMPILE_OPTIONS - -pthread - -Wall - -Wextra - -pedantic - -Wno-c++20-designator - -Wno-missing-field-initializers - -fomit-frame-pointer - -funroll-loops - -ftree-vectorize -) - -target_compile_options(cactus PRIVATE ${COMMON_COMPILE_OPTIONS}) -target_compile_options(cactus_static PRIVATE ${COMMON_COMPILE_OPTIONS}) - -if (${CMAKE_BUILD_TYPE} STREQUAL "Debug") +if(CMAKE_BUILD_TYPE STREQUAL "Debug") target_compile_options(cactus PRIVATE -DCACTUS_ANDROID_ENABLE_LOGGING) - target_compile_options(cactus_static PRIVATE -DCACTUS_ANDROID_ENABLE_LOGGING) -endif () - -set(OPTIMIZATION_OPTIONS - -O3 - -DNDEBUG - -ffunction-sections - -fdata-sections -) - -target_compile_options(cactus PRIVATE ${OPTIMIZATION_OPTIONS}) -target_compile_options(cactus_static PRIVATE ${OPTIMIZATION_OPTIONS}) - -target_compile_options(cactus PRIVATE -fvisibility=hidden -fvisibility-inlines-hidden) - -if (${ANDROID_ABI} STREQUAL "arm64-v8a") - set(ARM_OPTIONS - -march=armv8.2-a+fp16+simd+dotprod - ) - set(ARM_DEFINITIONS - __ARM_NEON=1 - __ARM_FEATURE_FP16_VECTOR_ARITHMETIC=1 - __ARM_FEATURE_DOTPROD=1 - ) - - target_compile_options(cactus PRIVATE ${ARM_OPTIONS}) - target_compile_options(cactus_static PRIVATE ${ARM_OPTIONS}) - - target_compile_definitions(cactus PRIVATE ${ARM_DEFINITIONS}) - target_compile_definitions(cactus_static PRIVATE ${ARM_DEFINITIONS}) -else() - message(FATAL_ERROR "Unsupported Android ABI: ${ANDROID_ABI}. Cactus only supports arm64-v8a due to ARM NEON requirements.") endif() -target_link_options(cactus PRIVATE -Wl,--gc-sections) -target_link_options(cactus PRIVATE -Wl,--exclude-libs,ALL) -target_link_options(cactus PRIVATE -flto) -target_link_options(cactus PRIVATE -Wl,-z,max-page-size=16384) +target_compile_options(cactus PRIVATE -fvisibility=hidden -fvisibility-inlines-hidden) +target_link_options(cactus PRIVATE -Wl,--gc-sections -Wl,--exclude-libs,ALL -flto -Wl,-z,max-page-size=16384) + +set(MRI_SCRIPT "${CMAKE_BINARY_DIR}/combine.mri") +file(GENERATE OUTPUT ${MRI_SCRIPT} CONTENT +"create ${CMAKE_BINARY_DIR}/lib/libcactus_static.a +addlib $ +addlib $ +addlib $ +save +end +") +add_custom_target(cactus_static ALL + COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/lib + COMMAND ${CMAKE_AR} -M < ${MRI_SCRIPT} + DEPENDS cactus_engine cactus_graph cactus_kernels + COMMENT "Merging static libraries into libcactus_static.a" +) -set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) -set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) diff --git a/android/Cactus.android.kt b/android/Cactus.android.kt deleted file mode 100644 index 2105f5c46..000000000 --- a/android/Cactus.android.kt +++ /dev/null @@ -1,115 +0,0 @@ -@file:JvmName("Cactus") -package com.cactus - -private object CactusJNI { - init { - System.loadLibrary("cactus") - nativeSetFramework() - } - - @JvmStatic external fun nativeSetFramework() - @JvmStatic external fun nativeGetLastError(): String - @JvmStatic external fun nativeSetCacheDir(cacheDir: String) - @JvmStatic external fun nativeSetAppId(appId: String) - @JvmStatic external fun nativeTelemetryFlush() - @JvmStatic external fun nativeTelemetryShutdown() - @JvmStatic external fun nativeInit(modelPath: String, corpusDir: String?, cacheIndex: Boolean): Long - @JvmStatic external fun nativeDestroy(handle: Long) - @JvmStatic external fun nativeReset(handle: Long) - @JvmStatic external fun nativeStop(handle: Long) - @JvmStatic external fun nativeComplete(handle: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String - @JvmStatic external fun nativePrefill(handle: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, pcmData: ByteArray?): String - @JvmStatic external fun nativeDetectLanguage(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String - @JvmStatic external fun nativeLogSetLevel(level: Int) - @JvmStatic external fun nativeLogSetCallback(callback: CactusLogCallback?) - @JvmStatic external fun nativeTranscribe(handle: Long, audioPath: String?, prompt: String?, optionsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String - @JvmStatic external fun nativeEmbed(handle: Long, text: String, normalize: Boolean): FloatArray - @JvmStatic external fun nativeRagQuery(handle: Long, query: String, topK: Int): String - @JvmStatic external fun nativeTokenize(handle: Long, text: String): IntArray - @JvmStatic external fun nativeScoreWindow(handle: Long, tokens: IntArray, start: Int, end: Int, context: Int): String - @JvmStatic external fun nativeImageEmbed(handle: Long, imagePath: String): FloatArray - @JvmStatic external fun nativeAudioEmbed(handle: Long, audioPath: String): FloatArray - @JvmStatic external fun nativeVad(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String - @JvmStatic external fun nativeDiarize(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String - @JvmStatic external fun nativeEmbedSpeaker(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?, maskWeights: FloatArray?): String - @JvmStatic external fun nativeStreamTranscribeInit(handle: Long, optionsJson: String?): Long - @JvmStatic external fun nativeStreamTranscribeProcess(handle: Long, pcmData: ByteArray): String - @JvmStatic external fun nativeStreamTranscribeStop(handle: Long): String - @JvmStatic external fun nativeIndexInit(indexDir: String, embeddingDim: Int): Long - @JvmStatic external fun nativeIndexAdd(handle: Long, ids: IntArray, documents: Array, metadatas: Array?, embeddings: Array, embeddingDim: Long): Int - @JvmStatic external fun nativeIndexDelete(handle: Long, ids: IntArray): Int - @JvmStatic external fun nativeIndexGet(handle: Long, ids: IntArray): String - @JvmStatic external fun nativeIndexQuery(handle: Long, embedding: FloatArray, topK: Long, optionsJson: String?): String - @JvmStatic external fun nativeIndexCompact(handle: Long): Int - @JvmStatic external fun nativeIndexDestroy(handle: Long) -} - -actual fun cactusInit(modelPath: String, corpusDir: String?, cacheIndex: Boolean): Long { - val h = CactusJNI.nativeInit(modelPath, corpusDir, cacheIndex) - if (h == 0L) throw RuntimeException(CactusJNI.nativeGetLastError().ifEmpty { "Failed to initialize model" }) - return h -} -actual fun cactusDestroy(model: Long) = CactusJNI.nativeDestroy(model) -actual fun cactusReset(model: Long) = CactusJNI.nativeReset(model) -actual fun cactusStop(model: Long) = CactusJNI.nativeStop(model) -actual fun cactusGetLastError(): String = CactusJNI.nativeGetLastError() -actual fun cactusSetTelemetryEnvironment(cacheDir: String) = CactusJNI.nativeSetCacheDir(cacheDir) -actual fun cactusSetAppId(appId: String) = CactusJNI.nativeSetAppId(appId) -actual fun cactusTelemetryFlush() = CactusJNI.nativeTelemetryFlush() -actual fun cactusTelemetryShutdown() = CactusJNI.nativeTelemetryShutdown() -actual fun cactusComplete(model: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String = - CactusJNI.nativeComplete(model, messagesJson, optionsJson, toolsJson, callback, pcmData) -actual fun cactusPrefill(model: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, pcmData: ByteArray?): String = - CactusJNI.nativePrefill(model, messagesJson, optionsJson, toolsJson, pcmData) -actual fun cactusTranscribe(model: Long, audioPath: String?, prompt: String?, optionsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String = - CactusJNI.nativeTranscribe(model, audioPath, prompt, optionsJson, callback, pcmData) -actual fun cactusEmbed(model: Long, text: String, normalize: Boolean): FloatArray = - CactusJNI.nativeEmbed(model, text, normalize) -actual fun cactusImageEmbed(model: Long, imagePath: String): FloatArray = - CactusJNI.nativeImageEmbed(model, imagePath) -actual fun cactusAudioEmbed(model: Long, audioPath: String): FloatArray = - CactusJNI.nativeAudioEmbed(model, audioPath) -actual fun cactusVad(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String = - CactusJNI.nativeVad(model, audioPath, optionsJson, pcmData) -actual fun cactusDiarize(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String = - CactusJNI.nativeDiarize(model, audioPath, optionsJson, pcmData) -actual fun cactusEmbedSpeaker(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?, maskWeights: FloatArray?): String = - CactusJNI.nativeEmbedSpeaker(model, audioPath, optionsJson, pcmData, maskWeights) -actual fun cactusRagQuery(model: Long, query: String, topK: Int): String = - CactusJNI.nativeRagQuery(model, query, topK) -actual fun cactusTokenize(model: Long, text: String): IntArray = - CactusJNI.nativeTokenize(model, text) -actual fun cactusScoreWindow(model: Long, tokens: IntArray, start: Int, end: Int, context: Int): String = - CactusJNI.nativeScoreWindow(model, tokens, start, end, context) -actual fun cactusStreamTranscribeStart(model: Long, optionsJson: String?): Long { - val h = CactusJNI.nativeStreamTranscribeInit(model, optionsJson) - if (h == 0L) throw RuntimeException(CactusJNI.nativeGetLastError().ifEmpty { "Failed to create stream transcriber" }) - return h -} -actual fun cactusStreamTranscribeProcess(stream: Long, pcmData: ByteArray): String = - CactusJNI.nativeStreamTranscribeProcess(stream, pcmData) -actual fun cactusStreamTranscribeStop(stream: Long): String = - CactusJNI.nativeStreamTranscribeStop(stream) -actual fun cactusIndexInit(indexDir: String, embeddingDim: Int): Long { - val h = CactusJNI.nativeIndexInit(indexDir, embeddingDim) - if (h == 0L) throw RuntimeException("Failed to initialize index") - return h -} -actual fun cactusIndexAdd(index: Long, ids: IntArray, documents: Array, embeddings: Array, metadatas: Array?): Int = - CactusJNI.nativeIndexAdd(index, ids, documents, metadatas, embeddings, embeddings[0].size.toLong()) -actual fun cactusIndexDelete(index: Long, ids: IntArray): Int = - CactusJNI.nativeIndexDelete(index, ids) -actual fun cactusIndexGet(index: Long, ids: IntArray): String = - CactusJNI.nativeIndexGet(index, ids) -actual fun cactusIndexQuery(index: Long, embedding: FloatArray, optionsJson: String?): String = - CactusJNI.nativeIndexQuery(index, embedding, 1000L, optionsJson) -actual fun cactusIndexCompact(index: Long): Int = - CactusJNI.nativeIndexCompact(index) -actual fun cactusIndexDestroy(index: Long) = - CactusJNI.nativeIndexDestroy(index) -actual fun cactusDetectLanguage(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String = - CactusJNI.nativeDetectLanguage(model, audioPath, optionsJson, pcmData) -actual fun cactusLogSetLevel(level: Int) = - CactusJNI.nativeLogSetLevel(level) -actual fun cactusLogSetCallback(callback: CactusLogCallback?) = - CactusJNI.nativeLogSetCallback(callback) diff --git a/android/Cactus.common.kt b/android/Cactus.common.kt deleted file mode 100644 index 51bbf0609..000000000 --- a/android/Cactus.common.kt +++ /dev/null @@ -1,44 +0,0 @@ -package com.cactus - -fun interface CactusTokenCallback { - fun onToken(token: String, tokenId: Int) -} - -fun interface CactusLogCallback { - fun onLog(level: Int, component: String, message: String) -} - -expect fun cactusInit(modelPath: String, corpusDir: String?, cacheIndex: Boolean): Long -expect fun cactusDestroy(model: Long) -expect fun cactusReset(model: Long) -expect fun cactusStop(model: Long) -expect fun cactusGetLastError(): String -expect fun cactusSetTelemetryEnvironment(cacheDir: String) -expect fun cactusSetAppId(appId: String) -expect fun cactusTelemetryFlush() -expect fun cactusTelemetryShutdown() -expect fun cactusComplete(model: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray? = null): String -expect fun cactusPrefill(model: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, pcmData: ByteArray? = null): String -expect fun cactusTranscribe(model: Long, audioPath: String?, prompt: String?, optionsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String -expect fun cactusEmbed(model: Long, text: String, normalize: Boolean): FloatArray -expect fun cactusImageEmbed(model: Long, imagePath: String): FloatArray -expect fun cactusAudioEmbed(model: Long, audioPath: String): FloatArray -expect fun cactusVad(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String -expect fun cactusRagQuery(model: Long, query: String, topK: Int): String -expect fun cactusTokenize(model: Long, text: String): IntArray -expect fun cactusScoreWindow(model: Long, tokens: IntArray, start: Int, end: Int, context: Int): String -expect fun cactusStreamTranscribeStart(model: Long, optionsJson: String?): Long -expect fun cactusStreamTranscribeProcess(stream: Long, pcmData: ByteArray): String -expect fun cactusStreamTranscribeStop(stream: Long): String -expect fun cactusIndexInit(indexDir: String, embeddingDim: Int): Long -expect fun cactusIndexAdd(index: Long, ids: IntArray, documents: Array, embeddings: Array, metadatas: Array?): Int -expect fun cactusIndexDelete(index: Long, ids: IntArray): Int -expect fun cactusIndexGet(index: Long, ids: IntArray): String -expect fun cactusIndexQuery(index: Long, embedding: FloatArray, optionsJson: String?): String -expect fun cactusIndexCompact(index: Long): Int -expect fun cactusIndexDestroy(index: Long) -expect fun cactusDetectLanguage(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String -expect fun cactusDiarize(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String -expect fun cactusEmbedSpeaker(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?, maskWeights: FloatArray? = null): String -expect fun cactusLogSetLevel(level: Int) -expect fun cactusLogSetCallback(callback: CactusLogCallback?) diff --git a/android/Cactus.ios.kt b/android/Cactus.ios.kt deleted file mode 100644 index 22fbd2947..000000000 --- a/android/Cactus.ios.kt +++ /dev/null @@ -1,517 +0,0 @@ -package com.cactus - -import cactus.* -import kotlinx.cinterop.* - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusInit(modelPath: String, corpusDir: String?, cacheIndex: Boolean): Long { - val ptr = cactus_init(modelPath, corpusDir, cacheIndex) - ?: throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Failed to initialize model") - return ptr.rawValue.toLong() -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusDestroy(model: Long) { - cactus_destroy(model.toCPointer()) -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusReset(model: Long) { cactus_reset(model.toCPointer()) } - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusStop(model: Long) { cactus_stop(model.toCPointer()) } - -actual fun cactusGetLastError(): String = cactus_get_last_error()?.toKString() ?: "" - -actual fun cactusSetTelemetryEnvironment(cacheDir: String) { - cactus_set_telemetry_environment(null, cacheDir, null) -} - -actual fun cactusSetAppId(appId: String) { cactus_set_app_id(appId) } - -actual fun cactusTelemetryFlush() { cactus_telemetry_flush() } - -actual fun cactusTelemetryShutdown() { cactus_telemetry_shutdown() } - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusComplete(model: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String { - memScoped { - val buffer = allocArray(65536) - val callbackRef = callback?.let { StableRef.create(it) } - val pcmPtr = pcmData?.refTo(0)?.getPointer(this) - try { - val result = cactus_complete( - model.toCPointer(), - messagesJson, - buffer, - 65536u, - optionsJson, - toolsJson, - callbackRef?.let { - staticCFunction?, UInt, COpaquePointer?, Unit> { token, tokenId, userData -> - if (token != null && userData != null) { - userData.asStableRef().get().onToken(token.toKString(), tokenId.toInt()) - } - } - }, - callbackRef?.asCPointer(), - pcmPtr?.reinterpret(), - pcmData?.size?.toULong() ?: 0u - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } finally { - callbackRef?.dispose() - } - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusPrefill(model: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, pcmData: ByteArray?): String { - memScoped { - val buffer = allocArray(65536) - val pcmPtr = pcmData?.refTo(0)?.getPointer(this) - val result = cactus_prefill( - model.toCPointer(), - messagesJson, - buffer, - 65536u, - optionsJson, - toolsJson, - pcmPtr?.reinterpret(), - pcmData?.size?.toULong() ?: 0u - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusTranscribe(model: Long, audioPath: String?, prompt: String?, optionsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String { - memScoped { - val buffer = allocArray(65536) - val callbackRef = callback?.let { StableRef.create(it) } - val pcmPtr = pcmData?.refTo(0)?.getPointer(this) - try { - val result = cactus_transcribe( - model.toCPointer(), - audioPath, - prompt, - buffer, - 65536u, - optionsJson, - callbackRef?.let { - staticCFunction?, UInt, COpaquePointer?, Unit> { token, tokenId, userData -> - if (token != null && userData != null) { - userData.asStableRef().get().onToken(token.toKString(), tokenId.toInt()) - } - } - }, - callbackRef?.asCPointer(), - pcmPtr?.reinterpret(), - pcmData?.size?.toULong() ?: 0u - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } finally { - callbackRef?.dispose() - } - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusEmbed(model: Long, text: String, normalize: Boolean): FloatArray { - memScoped { - val buffer = allocArray(4096) - val dimPtr = alloc() - val result = cactus_embed(model.toCPointer(), text, buffer, 4096u, dimPtr.ptr, normalize) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return FloatArray(dimPtr.value.toInt()) { buffer[it] } - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusImageEmbed(model: Long, imagePath: String): FloatArray { - memScoped { - val buffer = allocArray(4096) - val dimPtr = alloc() - val result = cactus_image_embed(model.toCPointer(), imagePath, buffer, 4096u, dimPtr.ptr) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return FloatArray(dimPtr.value.toInt()) { buffer[it] } - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusAudioEmbed(model: Long, audioPath: String): FloatArray { - memScoped { - val buffer = allocArray(4096) - val dimPtr = alloc() - val result = cactus_audio_embed(model.toCPointer(), audioPath, buffer, 4096u, dimPtr.ptr) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return FloatArray(dimPtr.value.toInt()) { buffer[it] } - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusVad(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String { - memScoped { - val buffer = allocArray(65536) - val pcmPtr = pcmData?.refTo(0)?.getPointer(this) - val result = cactus_vad( - model.toCPointer(), audioPath, buffer, 65536u, optionsJson, - pcmPtr?.reinterpret(), pcmData?.size?.toULong() ?: 0u - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusRagQuery(model: Long, query: String, topK: Int): String { - memScoped { - val buffer = allocArray(65536) - val result = cactus_rag_query(model.toCPointer(), query, buffer, 65536u, topK.toULong()) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusTokenize(model: Long, text: String): IntArray { - memScoped { - val buffer = allocArray(8192) - val tokenLen = alloc() - val result = cactus_tokenize(model.toCPointer(), text, buffer, 8192u, tokenLen.ptr) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return IntArray(tokenLen.value.toInt()) { buffer[it].toInt() } - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusScoreWindow(model: Long, tokens: IntArray, start: Int, end: Int, context: Int): String { - memScoped { - val buffer = allocArray(65536) - val tokenBuffer = allocArray(tokens.size) - tokens.forEachIndexed { i, v -> tokenBuffer[i] = v.toUInt() } - val result = cactus_score_window( - model.toCPointer(), tokenBuffer, tokens.size.toULong(), - start.toULong(), end.toULong(), context.toULong(), - buffer, 65536u - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusStreamTranscribeStart(model: Long, optionsJson: String?): Long { - val ptr = cactus_stream_transcribe_start(model.toCPointer(), optionsJson) - ?: throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Failed to create stream transcriber") - return ptr.rawValue.toLong() -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusStreamTranscribeProcess(stream: Long, pcmData: ByteArray): String { - memScoped { - val buffer = allocArray(65536) - val pcmPtr = pcmData.refTo(0).getPointer(this) - val result = cactus_stream_transcribe_process( - stream.toCPointer(), pcmPtr.reinterpret(), pcmData.size.toULong(), buffer, 65536u - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusStreamTranscribeStop(stream: Long): String { - memScoped { - val buffer = allocArray(65536) - val result = cactus_stream_transcribe_stop(stream.toCPointer(), buffer, 65536u) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusIndexInit(indexDir: String, embeddingDim: Int): Long { - val ptr = cactus_index_init(indexDir, embeddingDim.toULong()) - ?: throw RuntimeException("Failed to initialize index") - return ptr.rawValue.toLong() -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusIndexAdd(index: Long, ids: IntArray, documents: Array, embeddings: Array, metadatas: Array?): Int { - memScoped { - val idPtr = allocArray(ids.size) - ids.forEachIndexed { i, v -> idPtr[i] = v } - val docPtrs = allocArray>(documents.size) - documents.forEachIndexed { i, doc -> docPtrs[i] = doc.cstr.ptr } - val metaPtrs = metadatas?.let { - val ptrs = allocArray>(it.size) - it.forEachIndexed { i, meta -> ptrs[i] = meta.cstr.ptr } - ptrs - } - val embPtrs = allocArray>(embeddings.size) - embeddings.forEachIndexed { i, emb -> - val embArr = allocArray(emb.size) - emb.forEachIndexed { j, v -> embArr[j] = v } - embPtrs[i] = embArr - } - val result = cactus_index_add( - index.toCPointer(), idPtr, docPtrs, metaPtrs, embPtrs, - ids.size.toULong(), embeddings[0].size.toULong() - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return result - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusIndexDelete(index: Long, ids: IntArray): Int { - memScoped { - val idPtr = allocArray(ids.size) - ids.forEachIndexed { i, v -> idPtr[i] = v } - val result = cactus_index_delete(index.toCPointer(), idPtr, ids.size.toULong()) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return result - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusIndexGet(index: Long, ids: IntArray): String { - memScoped { - val count = ids.size - val idPtr = allocArray(count) - ids.forEachIndexed { i, v -> idPtr[i] = v } - - val docBufSize = 4096 - val embBufSize = 4096 - - val docRaw = Array(count) { allocArray(docBufSize) } - val metaRaw = Array(count) { allocArray(docBufSize) } - val embRaw = Array(count) { allocArray(embBufSize) } - - val docBuffers = allocArray>(count) - val docBufferSizes = allocArray(count) - val metaBuffers = allocArray>(count) - val metaBufferSizes = allocArray(count) - val embBuffers = allocArray>(count) - val embBufferSizes = allocArray(count) - - for (i in 0 until count) { - docBuffers[i] = docRaw[i] - docBufferSizes[i] = docBufSize.toULong() - metaBuffers[i] = metaRaw[i] - metaBufferSizes[i] = docBufSize.toULong() - embBuffers[i] = embRaw[i] - embBufferSizes[i] = embBufSize.toULong() - } - - val result = cactus_index_get( - index.toCPointer(), idPtr, count.toULong(), - docBuffers, docBufferSizes, metaBuffers, metaBufferSizes, - embBuffers, embBufferSizes - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - val sb = StringBuilder("{\"results\":[") - for (i in 0 until count) { - if (i > 0) sb.append(",") - sb.append("{\"document\":\"${docRaw[i].toKString()}\"") - val meta = metaRaw[i].toKString() - if (meta.isNotEmpty()) sb.append(",\"metadata\":\"$meta\"") else sb.append(",\"metadata\":null") - sb.append(",\"embedding\":[") - val embDim = embBufferSizes[i].toInt() - for (j in 0 until embDim) { - if (j > 0) sb.append(",") - sb.append(embRaw[i][j]) - } - sb.append("]}") - } - sb.append("]}") - return sb.toString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusIndexQuery(index: Long, embedding: FloatArray, optionsJson: String?): String { - val topK = 1000L - memScoped { - val embArr = allocArray(embedding.size) - embedding.forEachIndexed { i, v -> embArr[i] = v } - val embPtr = alloc>() - embPtr.value = embArr - val idBuffer = allocArray(topK) - val scoreBuffer = allocArray(topK) - val idBufferSize = alloc() - val scoreBufferSize = alloc() - idBufferSize.value = topK.toULong() - scoreBufferSize.value = topK.toULong() - val idPtrPtr = alloc>() - idPtrPtr.value = idBuffer - val scorePtrPtr = alloc>() - scorePtrPtr.value = scoreBuffer - val result = cactus_index_query( - index.toCPointer(), embPtr.ptr, 1u, embedding.size.toULong(), optionsJson, - idPtrPtr.ptr, idBufferSize.ptr, scorePtrPtr.ptr, scoreBufferSize.ptr - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - val sb = StringBuilder("{\"results\":[") - for (i in 0 until idBufferSize.value.toInt()) { - if (i > 0) sb.append(",") - sb.append("{\"id\":${idBuffer[i]},\"score\":${scoreBuffer[i]}}") - } - sb.append("]}") - return sb.toString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusIndexCompact(index: Long): Int { - val result = cactus_index_compact(index.toCPointer()) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return result -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusIndexDestroy(index: Long) { - cactus_index_destroy(index.toCPointer()) -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusDetectLanguage(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String { - memScoped { - val buffer = allocArray(65536) - val pcmPtr = pcmData?.refTo(0)?.getPointer(this) - val result = cactus_detect_language( - model.toCPointer(), audioPath, buffer, 65536u, optionsJson, - pcmPtr?.reinterpret(), pcmData?.size?.toULong() ?: 0u - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusDiarize(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String { - memScoped { - val buffer = allocArray(65536) - val pcmPtr = pcmData?.refTo(0)?.getPointer(this) - val result = cactus_diarize( - model.toCPointer(), audioPath, buffer, 65536u, optionsJson, - pcmPtr?.reinterpret(), pcmData?.size?.toULong() ?: 0u - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } -} - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusEmbedSpeaker(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?, maskWeights: FloatArray?): String { - memScoped { - val buffer = allocArray(65536) - val pcmPtr = pcmData?.refTo(0)?.getPointer(this) - val maskPtr = maskWeights?.let { - val arr = allocArray(it.size) - it.forEachIndexed { i, v -> arr[i] = v } - arr - } - val result = cactus_embed_speaker( - model.toCPointer(), audioPath, buffer, 65536u, optionsJson, - pcmPtr?.reinterpret(), pcmData?.size?.toULong() ?: 0u, - maskPtr, maskWeights?.size?.toULong() ?: 0u - ) - if (result < 0) { - val error = cactus_get_last_error()?.toKString() ?: "Unknown error" - throw RuntimeException(error) - } - return buffer.toKString() - } -} - -actual fun cactusLogSetLevel(level: Int) { - cactus_log_set_level(level) -} - -private var _logCallbackRef: StableRef? = null - -@OptIn(ExperimentalForeignApi::class) -actual fun cactusLogSetCallback(callback: CactusLogCallback?) { - _logCallbackRef?.dispose() - _logCallbackRef = null - if (callback == null) { - cactus_log_set_callback(null, null) - } else { - val callbackRef = StableRef.create(callback) - _logCallbackRef = callbackRef - cactus_log_set_callback( - staticCFunction?, CPointer?, COpaquePointer?, Unit> { level, component, message, userData -> - if (userData != null) { - userData.asStableRef().get().onLog( - level, - component?.toKString() ?: "", - message?.toKString() ?: "" - ) - } - }, - callbackRef.asCPointer() - ) - } -} diff --git a/android/Cactus.kt b/android/Cactus.kt deleted file mode 100644 index 9e7df7907..000000000 --- a/android/Cactus.kt +++ /dev/null @@ -1,515 +0,0 @@ -package com.cactus - -import org.json.JSONArray -import org.json.JSONObject -import java.io.Closeable - -class Cactus private constructor(private var handle: Long) : Closeable { - - companion object { - init { - System.loadLibrary("cactus") - } - - @JvmStatic - fun create(modelPath: String, corpusDir: String? = null): Cactus { - val handle = nativeInit(modelPath, corpusDir) - if (handle == 0L) { - throw CactusException(nativeGetLastError().ifEmpty { "Failed to initialize model" }) - } - return Cactus(handle) - } - - @JvmStatic - private external fun nativeInit(modelPath: String, corpusDir: String?): Long - @JvmStatic - private external fun nativeGetLastError(): String - } - - fun complete(prompt: String, options: CompletionOptions = CompletionOptions()): CompletionResult { - return complete(listOf(Message.user(prompt)), options) - } - - fun complete( - messages: List, - options: CompletionOptions = CompletionOptions(), - tools: List>? = null, - callback: TokenCallback? = null - ): CompletionResult { - checkHandle() - val messagesJson = JSONArray(messages.map { it.toJson() }).toString() - val toolsJson = tools?.let { JSONArray(it.map { t -> JSONObject(t) }).toString() } - - val responseJson = nativeComplete(handle, messagesJson, options.toJson(), toolsJson, callback) - val json = JSONObject(responseJson) - - if (json.has("error") && !json.isNull("error")) { - throw CactusException(json.getString("error")) - } - - return json.toCompletionResult() - } - - fun transcribe( - audioPath: String, - prompt: String? = null, - language: String? = null, - translate: Boolean = false - ): TranscriptionResult { - checkHandle() - val optionsJson = JSONObject().apply { - language?.let { put("language", it) } - put("translate", translate) - }.toString() - - val responseJson = nativeTranscribe(handle, audioPath, prompt, optionsJson, null) - val json = JSONObject(responseJson) - - if (json.has("error") && !json.isNull("error")) { - throw CactusException(json.getString("error")) - } - - return json.toTranscriptionResult() - } - - fun transcribe( - pcmData: ByteArray, - prompt: String? = null, - language: String? = null, - translate: Boolean = false - ): TranscriptionResult { - checkHandle() - val optionsJson = JSONObject().apply { - language?.let { put("language", it) } - put("translate", translate) - }.toString() - - val responseJson = nativeTranscribe(handle, null, prompt, optionsJson, pcmData) - val json = JSONObject(responseJson) - - if (json.has("error") && !json.isNull("error")) { - throw CactusException(json.getString("error")) - } - - return json.toTranscriptionResult() - } - - fun embed(text: String, normalize: Boolean = true): FloatArray { - checkHandle() - return nativeEmbed(handle, text, normalize) - ?: throw CactusException(nativeGetLastError().ifEmpty { "Failed to generate embedding" }) - } - - fun ragQuery(query: String, topK: Int = 5): String { - checkHandle() - val responseJson = nativeRagQuery(handle, query, topK) - val json = JSONObject(responseJson) - - if (json.has("error")) { - throw CactusException(json.getString("error")) - } - - return responseJson - } - - fun reset() { - checkHandle() - nativeReset(handle) - } - - fun stop() { - checkHandle() - nativeStop(handle) - } - - fun tokenize(text: String): IntArray { - checkHandle() - return nativeTokenize(handle, text) - ?: throw CactusException(nativeGetLastError().ifEmpty { "Failed to tokenize" }) - } - - fun scoreWindow(tokens: IntArray, start: Int, end: Int, context: Int): String { - checkHandle() - val responseJson = nativeScoreWindow(handle, tokens, start, end, context) - val json = JSONObject(responseJson) - if (json.has("error")) { - throw CactusException(json.getString("error")) - } - return responseJson - } - - fun imageEmbed(imagePath: String): FloatArray { - checkHandle() - return nativeImageEmbed(handle, imagePath) - ?: throw CactusException(nativeGetLastError().ifEmpty { "Failed to generate image embedding" }) - } - - fun audioEmbed(audioPath: String): FloatArray { - checkHandle() - return nativeAudioEmbed(handle, audioPath) - ?: throw CactusException(nativeGetLastError().ifEmpty { "Failed to generate audio embedding" }) - } - - fun vad(audioPath: String, options: VADOptions = VADOptions()): VADResult { - checkHandle() - val optionsJson = options.toJson() - val responseJson = nativeVad(handle, audioPath, optionsJson, null) - val json = JSONObject(responseJson) - - if (json.has("error") && !json.isNull("error")) { - throw CactusException(json.getString("error")) - } - - return json.toVADResult() - } - - fun vad(pcmData: ByteArray, options: VADOptions = VADOptions()): VADResult { - checkHandle() - val optionsJson = options.toJson() - val responseJson = nativeVad(handle, null, optionsJson, pcmData) - val json = JSONObject(responseJson) - - if (json.has("error") && !json.isNull("error")) { - throw CactusException(json.getString("error")) - } - - return json.toVADResult() - } - - fun createStreamTranscriber(): StreamTranscriber { - checkHandle() - val streamHandle = nativeStreamTranscribeInit(handle) - if (streamHandle == 0L) { - throw CactusException(nativeGetLastError().ifEmpty { "Failed to create stream transcriber" }) - } - return StreamTranscriber(streamHandle) - } - - override fun close() { - if (handle != 0L) { - nativeDestroy(handle) - handle = 0L - } - } - - private fun checkHandle() { - if (handle == 0L) { - throw CactusException("Model has been closed") - } - } - - private external fun nativeDestroy(handle: Long) - private external fun nativeReset(handle: Long) - private external fun nativeStop(handle: Long) - private external fun nativeComplete(handle: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, callback: TokenCallback?): String - private external fun nativeTranscribe(handle: Long, audioPath: String?, prompt: String?, optionsJson: String?, pcmData: ByteArray?): String - private external fun nativeEmbed(handle: Long, text: String, normalize: Boolean): FloatArray? - private external fun nativeRagQuery(handle: Long, query: String, topK: Int): String - private external fun nativeTokenize(handle: Long, text: String): IntArray? - private external fun nativeScoreWindow(handle: Long, tokens: IntArray, start: Int, end: Int, context: Int): String - private external fun nativeImageEmbed(handle: Long, imagePath: String): FloatArray? - private external fun nativeAudioEmbed(handle: Long, audioPath: String): FloatArray? - private external fun nativeVad(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String - private external fun nativeStreamTranscribeInit(handle: Long): Long -} - -class StreamTranscriber internal constructor(private var handle: Long) : Closeable { - - /** - * Process a chunk of PCM audio data and get intermediate transcription results. - * @param pcmData Raw PCM audio data (16-bit signed, mono, 16kHz) - * @return Intermediate transcription result - */ - fun process(pcmData: ByteArray): TranscriptionResult { - checkHandle() - val responseJson = nativeStreamTranscribeProcess(handle, pcmData) - val json = JSONObject(responseJson) - if (json.has("error")) { - throw CactusException(json.getString("error")) - } - return json.toTranscriptionResult() - } - - /** - * Stop the streaming transcription and get the final result. - * This also releases the stream resources. - * @return Final transcription result - */ - fun stop(): TranscriptionResult { - checkHandle() - val responseJson = nativeStreamTranscribeStop(handle) - handle = 0L // Stream is now closed - val json = JSONObject(responseJson) - if (json.has("error")) { - throw CactusException(json.getString("error")) - } - return json.toTranscriptionResult() - } - - override fun close() { - if (handle != 0L) { - // Stop also closes the stream - try { - nativeStreamTranscribeStop(handle) - } catch (_: Exception) { - // Ignore errors during close - } - handle = 0L - } - } - - private fun checkHandle() { - if (handle == 0L) { - throw CactusException("Stream transcriber has been closed") - } - } - - private external fun nativeStreamTranscribeProcess(handle: Long, pcmData: ByteArray): String - private external fun nativeStreamTranscribeStop(handle: Long): String -} - -class CactusIndex private constructor(private var handle: Long) : Closeable { - - companion object { - init { - System.loadLibrary("cactus") - } - - @JvmStatic - fun create(indexDir: String, embeddingDim: Int): CactusIndex { - val handle = nativeIndexInit(indexDir, embeddingDim) - if (handle == 0L) { - throw CactusException("Failed to initialize index") - } - return CactusIndex(handle) - } - - @JvmStatic - private external fun nativeIndexInit(indexDir: String, embeddingDim: Int): Long - } - - fun add( - ids: IntArray, - documents: Array, - embeddings: Array, - metadatas: Array? = null - ) { - checkHandle() - val result = nativeIndexAdd(handle, ids, documents, metadatas, embeddings, embeddings[0].size) - if (result < 0) { - throw CactusException("Failed to add documents to index") - } - } - - fun delete(ids: IntArray) { - checkHandle() - val result = nativeIndexDelete(handle, ids) - if (result < 0) { - throw CactusException("Failed to delete documents from index") - } - } - - fun query(embedding: FloatArray, topK: Int = 5): List { - checkHandle() - val responseJson = nativeIndexQuery(handle, embedding, topK, null) - val json = JSONObject(responseJson) - if (json.has("error")) { - throw CactusException(json.getString("error")) - } - val results = json.getJSONArray("results") - return (0 until results.length()).map { i -> - val obj = results.getJSONObject(i) - IndexResult(obj.getInt("id"), obj.getDouble("score").toFloat()) - } - } - - fun compact() { - checkHandle() - val result = nativeIndexCompact(handle) - if (result < 0) { - throw CactusException("Failed to compact index") - } - } - - override fun close() { - if (handle != 0L) { - nativeIndexDestroy(handle) - handle = 0L - } - } - - private fun checkHandle() { - if (handle == 0L) { - throw CactusException("Index has been closed") - } - } - - private external fun nativeIndexAdd(handle: Long, ids: IntArray, documents: Array, metadatas: Array?, embeddings: Array, embeddingDim: Int): Int - private external fun nativeIndexDelete(handle: Long, ids: IntArray): Int - private external fun nativeIndexQuery(handle: Long, embedding: FloatArray, topK: Int, optionsJson: String?): String - private external fun nativeIndexCompact(handle: Long): Int - private external fun nativeIndexDestroy(handle: Long) -} - -data class IndexResult(val id: Int, val score: Float) - -data class Message(val role: String, val content: String) { - companion object { - fun system(content: String) = Message("system", content) - fun user(content: String) = Message("user", content) - fun assistant(content: String) = Message("assistant", content) - } - - fun toJson(): JSONObject = JSONObject().apply { - put("role", role) - put("content", content) - } -} - -data class CompletionOptions( - val temperature: Float = 0.7f, - val topP: Float = 0.9f, - val topK: Int = 40, - val maxTokens: Int = 512, - val stopSequences: List = emptyList(), - val confidenceThreshold: Float = 0f -) { - fun toJson(): String = JSONObject().apply { - put("temperature", temperature) - put("top_p", topP) - put("top_k", topK) - put("max_tokens", maxTokens) - put("stop", JSONArray(stopSequences)) - put("confidence_threshold", confidenceThreshold) - }.toString() -} - -data class CompletionResult( - val text: String, - val functionCalls: List>?, - val promptTokens: Int, - val completionTokens: Int, - val timeToFirstToken: Double, - val totalTime: Double, - val prefillTokensPerSecond: Double, - val decodeTokensPerSecond: Double, - val confidence: Double, - val needsCloudHandoff: Boolean -) - -data class TranscriptionResult( - val text: String, - val segments: List>?, - val totalTime: Double -) - -data class VADSegment( - val start: Int, - val end: Int -) - -data class VADResult( - val segments: List, - val totalTime: Double, - val ramUsage: Double -) - -data class VADOptions( - val threshold: Float? = null, - val negThreshold: Float? = null, - val minSpeechDurationMs: Int? = null, - val maxSpeechDurationS: Float? = null, - val minSilenceDurationMs: Int? = null, - val speechPadMs: Int? = null, - val windowSizeSamples: Int? = null, - val samplingRate: Int? = null -) { - fun toJson(): String? { - val options = JSONObject() - threshold?.let { options.put("threshold", it) } - negThreshold?.let { options.put("neg_threshold", it) } - minSpeechDurationMs?.let { options.put("min_speech_duration_ms", it) } - maxSpeechDurationS?.let { options.put("max_speech_duration_s", it) } - minSilenceDurationMs?.let { options.put("min_silence_duration_ms", it) } - speechPadMs?.let { options.put("speech_pad_ms", it) } - windowSizeSamples?.let { options.put("window_size_samples", it) } - samplingRate?.let { options.put("sampling_rate", it) } - return if (options.length() > 0) options.toString() else null - } -} - -fun interface TokenCallback { - fun onToken(token: String, tokenId: Int) -} - -class CactusException(message: String) : Exception(message) - -private fun JSONObject.toCompletionResult(): CompletionResult { - val functionCalls = optJSONArray("function_calls")?.let { arr -> - (0 until arr.length()).map { arr.getJSONObject(it).toMap() } - } - return CompletionResult( - text = optString("response", ""), - functionCalls = functionCalls, - promptTokens = optInt("prefill_tokens", 0), - completionTokens = optInt("decode_tokens", 0), - timeToFirstToken = optDouble("time_to_first_token_ms", 0.0), - totalTime = optDouble("total_time_ms", 0.0), - prefillTokensPerSecond = optDouble("prefill_tps", 0.0), - decodeTokensPerSecond = optDouble("decode_tps", 0.0), - confidence = optDouble("confidence", 1.0), - needsCloudHandoff = optBoolean("cloud_handoff", false) - ) -} - -private fun JSONObject.toTranscriptionResult(): TranscriptionResult { - val segments = optJSONArray("segments")?.let { arr -> - (0 until arr.length()).map { arr.getJSONObject(it).toMap() } - } - return TranscriptionResult( - text = optString("response", ""), - segments = segments, - totalTime = optDouble("total_time_ms", 0.0) - ) -} - -private fun JSONObject.toVADResult(): VADResult { - val segments = getJSONArray("segments").let { arr -> - (0 until arr.length()).map { i -> - val obj = arr.getJSONObject(i) - VADSegment( - start = obj.getInt("start"), - end = obj.getInt("end") - ) - } - } - return VADResult( - segments = segments, - totalTime = optDouble("total_time_ms", 0.0), - ramUsage = optDouble("ram_usage_mb", 0.0) - ) -} - -private fun JSONObject.toMap(): Map { - val map = mutableMapOf() - keys().forEach { key -> - map[key] = when (val value = get(key)) { - is JSONObject -> value.toMap() - is JSONArray -> value.toList() - JSONObject.NULL -> Unit - else -> value - } - } - return map -} - -private fun JSONArray.toList(): List { - return (0 until length()).map { i -> - when (val value = get(i)) { - is JSONObject -> value.toMap() - is JSONArray -> value.toList() - JSONObject.NULL -> Unit - else -> value - } - } -} diff --git a/android/README.md b/android/README.md index 41f07a3f3..2d8051dfc 100644 --- a/android/README.md +++ b/android/README.md @@ -1,458 +1,34 @@ ---- -title: "Cactus Android & Kotlin Multiplatform SDK" -description: "Kotlin API for running AI models on-device on Android and iOS via Kotlin Multiplatform. Supports completion, transcription, embeddings, RAG, and tool calling." -keywords: ["Android SDK", "Kotlin Multiplatform", "on-device AI", "mobile inference", "JNI", "KMP"] ---- +# Android Build -# Cactus for Android & Kotlin Multiplatform +Builds `libcactus` for Android (arm64-v8a). -Run AI models on-device with a simple Kotlin API. - -> **Model weights:** Pre-converted weights for all supported models at [huggingface.co/Cactus-Compute](https://huggingface.co/Cactus-Compute). - -## Building +## Usage - ```bash -git clone https://github.com/cactus-compute/cactus && cd cactus && source ./setup cactus build --android ``` -Build output: `android/libcactus.so` (and `android/libcactus.a`) - - -see the main [README.md](../README.md) for how to use CLI & download weight - -### Vendored libcurl (device builds) - -To bundle libcurl locally for Android device testing, place artifacts using: - -`libs/curl/android/arm64-v8a/libcurl.a` and `libs/curl/include/curl/*.h` - -The build auto-detects `libs/curl`. You can override with: +Or directly: ```bash -CACTUS_CURL_ROOT=/absolute/path/to/curl cactus build --android -``` - -## Integration - - -### Android-only - -1. Copy `libcactus.so` to `app/src/main/jniLibs/arm64-v8a/` -2. Copy `Cactus.kt` to `app/src/main/java/com/cactus/` - -### Kotlin Multiplatform - -Source files: - -| File | Copy to | -|------|---------| -| `Cactus.common.kt` | `shared/src/commonMain/kotlin/com/cactus/` | -| `Cactus.android.kt` | `shared/src/androidMain/kotlin/com/cactus/` | -| `Cactus.ios.kt` | `shared/src/iosMain/kotlin/com/cactus/` | -| `cactus.def` | `shared/src/nativeInterop/cinterop/` | - -Binary files: - -| Platform | Location | -|----------|----------| -| Android | `libcactus.so` → `app/src/main/jniLibs/arm64-v8a/` | -| iOS | `libcactus-device.a` → link via cinterop | - -build.gradle.kts: - -```kotlin -kotlin { - androidTarget() - - listOf(iosArm64(), iosSimulatorArm64()).forEach { - it.compilations.getByName("main") { - cinterops { - create("cactus") { - defFile("src/nativeInterop/cinterop/cactus.def") - includeDirs("/path/to/cactus/ffi") - } - } - } - it.binaries.framework { - linkerOpts("-L/path/to/apple", "-lcactus-device") - } - } - - sourceSets { - commonMain.dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0") - } - } -} -``` - - -## Usage - -Handles are plain `Long` values (C pointers). All functions are top-level. - -### Basic Completion - - -```kotlin -import com.cactus.* - -val model = cactusInit("/path/to/model", null, false) -val messages = """[{"role":"user","content":"What is the capital of France?"}]""" -val resultJson = cactusComplete(model, messages, null, null, null) -println(resultJson) -cactusDestroy(model) -``` - - -For vision models (LFM2-VL, LFM2.5-VL, Gemma4, Qwen3.5), add `"images": ["path/to/image.png"]` to any message. For audio models (Gemma4), add `"audio": ["path/to/audio.wav"]`. See [Engine API](/docs/cactus_engine.md) for details. - -### Completion with Options and Streaming - -```kotlin -import com.cactus.* - -val options = """{"max_tokens":256,"temperature":0.7}""" - -val resultJson = cactusComplete(model, messages, options, null) { token, _ -> - print(token) -} -println(resultJson) +bash android/build.sh ``` -### Prefill +## Output -Pre-processes input text and populates the KV cache without generating output tokens. This reduces latency for subsequent calls to `cactusComplete`. +- `libcactus.so` — Shared library (JNI, for Android apps) +- `libcactus.a` — Static library (for native test binaries) -```kotlin -fun cactusPrefill( - model: Long, - messagesJson: String, - optionsJson: String?, - toolsJson: String? -): String -``` - -```kotlin -val tools = """[ - { - "type": "function", - "function": { - "name": "get_weather", - "description": "Get weather for a location", - "parameters": { - "type": "object", - "properties": { - "location": {"type": "string", "description": "City, State, Country"} - }, - "required": ["location"] - } - } - } -]""" - -val messages = """[ - {"role": "system", "content": "You are a helpful assistant."}, - {"role": "user", "content": "What is the weather in Paris?"}, - {"role": "assistant", "content": "<|tool_call_start|>get_weather(location=\"Paris\")<|tool_call_end|>"}, - {"role": "tool", "content": "{\"name\": \"get_weather\", \"content\": \"Sunny, 72°F\"}"}, - {"role": "assistant", "content": "It's sunny and 72°F in Paris!"} -]""" - -val resultJson = cactusPrefill(model, messages, null, tools) - -val completionMessages = """[ - {"role": "system", "content": "You are a helpful assistant."}, - {"role": "user", "content": "What is the weather in Paris?"}, - {"role": "assistant", "content": "<|tool_call_start|>get_weather(location=\"Paris\")<|tool_call_end|>"}, - {"role": "tool", "content": "{\"name\": \"get_weather\", \"content\": \"Sunny, 72°F\"}"}, - {"role": "assistant", "content": "It's sunny and 72°F in Paris!"}, - {"role": "user", "content": "What about SF?"} -]""" - -val completion = cactusComplete(model, completionMessages, null, tools, null) -``` - -**Response format:** -```json -{ - "success": true, - "error": null, - "prefill_tokens": 25, - "prefill_tps": 166.1, - "total_time_ms": 150.5, - "ram_usage_mb": 245.67 -} -``` - -### Audio Transcription - -```kotlin -import com.cactus.* - -// From file -val resultJson = cactusTranscribe(model, "/path/to/audio.wav", null, null, null, null) -println(resultJson) - -// From PCM data (16 kHz mono) -val pcmData: ByteArray = ... -val resultJson2 = cactusTranscribe(model, null, null, null, null, pcmData) -println(resultJson2) -``` - -`segments` contains timestamps (seconds): phrase-level for Whisper, word-level for Parakeet TDT, one segment per transcription window for Parakeet CTC and Moonshine (consecutive VAD speech regions up to 30s). - -```kotlin -import org.json.JSONObject - -val result = JSONObject(resultJson) -val segments = result.getJSONArray("segments") -for (i in 0 until segments.length()) { - val seg = segments.getJSONObject(i) - println("[${seg.getDouble("start")}s - ${seg.getDouble("end")}s] ${seg.getString("text")}") -} -``` - -**Custom vocabulary** biases the decoder toward domain-specific words (supported for Whisper and Moonshine models). Pass `custom_vocabulary` and `vocabulary_boost` in the options JSON: - -```kotlin -val options = """{"custom_vocabulary": ["Omeprazole", "HIPAA", "Cactus"], "vocabulary_boost": 3.0}""" -val result = cactusTranscribe(model, "/path/to/audio.wav", "", options, null, null) -``` - -### Streaming Transcription - -```kotlin -val stream = cactusStreamTranscribeStart(model, null) -val partial = cactusStreamTranscribeProcess(stream, audioChunk) -val final_ = cactusStreamTranscribeStop(stream) -``` - -Streaming also accepts `custom_vocabulary` in the options passed to `cactusStreamTranscribeStart`. The bias is applied for the lifetime of the stream session. - -### Embeddings - -```kotlin -val embedding = cactusEmbed(model, "Hello, world!", true) // FloatArray -val imageEmbedding = cactusImageEmbed(model, "/path/to/image.jpg") -val audioEmbedding = cactusAudioEmbed(model, "/path/to/audio.wav") -``` - -### Tokenization - -```kotlin -val tokens = cactusTokenize(model, "Hello, world!") // IntArray -val scores = cactusScoreWindow(model, tokens, 0, tokens.size, 512) -``` - -### VAD - -```kotlin -val result = cactusVad(model, "/path/to/audio.wav", null, null) -``` +## Options -### Diarize - -```kotlin -val result = cactusDiarize(model, "/path/to/audio.wav", null, null) -``` - -Options (all optional): -- `step_ms` (int, default 1000) — sliding window stride in milliseconds -- `threshold` (float) — zero out per-speaker scores below this value -- `num_speakers` (int) — keep only the N most active speakers -- `min_speakers` / `max_speakers` (int) — speaker count bounds -- `raw_powerset` (bool, default false) — return raw 7-class powerset scores instead of 3-speaker probabilities - -### Embed Speaker - -```kotlin -val result = cactusEmbedSpeaker(model, "/path/to/audio.wav", null, null) - -// With diarization mask for speaker-specific embedding -val result = cactusEmbedSpeaker(model, "/path/to/audio.wav", null, null, maskWeights) -``` - -Returns a 256-dimensional speaker embedding. When `maskWeights` (a per-frame weight array from diarization) is provided, the embedding is extracted using weighted stats pooling for speaker-specific embeddings. - -### RAG - -```kotlin -val result = cactusRagQuery(model, "What is machine learning?", 5) -``` - -### Vector Index - -```kotlin -val index = cactusIndexInit("/path/to/index", 3) - -cactusIndexAdd( - index, - intArrayOf(1, 2), - arrayOf("Document 1", "Document 2"), - arrayOf(floatArrayOf(0.1f, 0.2f, 0.3f), floatArrayOf(0.4f, 0.5f, 0.6f)), - null -) - -val resultsJson = cactusIndexQuery(index, floatArrayOf(0.1f, 0.2f, 0.3f), null) -cactusIndexDelete(index, intArrayOf(2)) -cactusIndexCompact(index) -cactusIndexDestroy(index) -``` - -## API Reference - -All functions are top-level and mirror the C FFI directly. Handles are `Long` values. - -### Init / Lifecycle - -```kotlin -fun cactusInit(modelPath: String, corpusDir: String?, cacheIndex: Boolean): Long // throws RuntimeException -fun cactusDestroy(model: Long) -fun cactusReset(model: Long) -fun cactusStop(model: Long) -fun cactusGetLastError(): String -``` - -### Prefill - -```kotlin -fun cactusPrefill( - model: Long, - messagesJson: String, - optionsJson: String?, - toolsJson: String?, - pcmData: ByteArray? = null -): String -``` - -### Completion - -```kotlin -fun cactusComplete( - model: Long, - messagesJson: String, - optionsJson: String?, - toolsJson: String?, - callback: CactusTokenCallback?, - pcmData: ByteArray? = null -): String -``` - -### Transcription - -```kotlin -fun cactusTranscribe( - model: Long, - audioPath: String?, - prompt: String?, - optionsJson: String?, - callback: CactusTokenCallback?, - pcmData: ByteArray? -): String - -fun cactusStreamTranscribeStart(model: Long, optionsJson: String?): Long // throws RuntimeException -fun cactusStreamTranscribeProcess(stream: Long, pcmData: ByteArray): String -fun cactusStreamTranscribeStop(stream: Long): String -``` - -### Embeddings - -```kotlin -fun cactusEmbed(model: Long, text: String, normalize: Boolean): FloatArray -fun cactusImageEmbed(model: Long, imagePath: String): FloatArray -fun cactusAudioEmbed(model: Long, audioPath: String): FloatArray -``` - -### Tokenization / Scoring - -```kotlin -fun cactusTokenize(model: Long, text: String): IntArray -fun cactusScoreWindow(model: Long, tokens: IntArray, start: Int, end: Int, context: Int): String -``` - -### Detect Language - -```kotlin -fun cactusDetectLanguage(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String -``` - -### VAD - -```kotlin -fun cactusVad(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String -``` - -### Diarize - -```kotlin -fun cactusDiarize(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String -``` - -### Embed Speaker - -```kotlin -fun cactusEmbedSpeaker(model: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?, maskWeights: FloatArray? = null): String -``` - -### RAG - -```kotlin -fun cactusRagQuery(model: Long, query: String, topK: Int): String -``` - -### Vector Index - -```kotlin -fun cactusIndexInit(indexDir: String, embeddingDim: Int): Long // throws RuntimeException -fun cactusIndexDestroy(index: Long) -fun cactusIndexAdd(index: Long, ids: IntArray, documents: Array, embeddings: Array, metadatas: Array?): Int -fun cactusIndexDelete(index: Long, ids: IntArray): Int -fun cactusIndexGet(index: Long, ids: IntArray): String -fun cactusIndexQuery(index: Long, embedding: FloatArray, optionsJson: String?): String -fun cactusIndexCompact(index: Long): Int -``` - -### Logging - -```kotlin -fun cactusLogSetLevel(level: Int) // 0=DEBUG 1=INFO 2=WARN 3=ERROR 4=NONE -fun cactusLogSetCallback(callback: CactusLogCallback?) -``` - -### Telemetry - -```kotlin -fun cactusSetTelemetryEnvironment(cacheDir: String) -fun cactusSetAppId(appId: String) -fun cactusTelemetryFlush() -fun cactusTelemetryShutdown() -``` - -### Types - -```kotlin -fun interface CactusTokenCallback { - fun onToken(token: String, tokenId: Int) -} - -fun interface CactusLogCallback { - fun onLog(level: Int, component: String, message: String) -} -``` +| Variable | Default | Description | +|----------|---------|-------------| +| `ANDROID_NDK_HOME` | Auto-detected | Android NDK path | +| `ANDROID_PLATFORM` | `android-21` | Minimum API level | +| `CMAKE_BUILD_TYPE` | `Release` | CMake build type | +| `CACTUS_CURL_ROOT` | `cactus-engine/libs/curl` | Vendored libcurl path | ## Requirements -- Android API 21+ / arm64-v8a -- iOS 13+ / arm64 (KMP only) - -## See Also - -- [Cactus Engine API](/docs/cactus_engine.md) — Full C API reference underlying the Kotlin bindings -- [Cactus Index API](/docs/cactus_index.md) — Vector database API for RAG applications -- [Fine-tuning Guide](/docs/finetuning.md) — Deploy custom fine-tunes to Android -- [Swift SDK](/apple/) — Swift alternative for Apple platforms -- [Flutter SDK](/flutter/) — Cross-platform alternative using Dart +- Android NDK (install via Android Studio > SDK Tools > NDK) +- CMake 3.10+ diff --git a/android/cactus.def b/android/cactus.def deleted file mode 100644 index cf3e7ba7e..000000000 --- a/android/cactus.def +++ /dev/null @@ -1,3 +0,0 @@ -package = cactus -headers = cactus_ffi.h -headerFilter = cactus_ffi.h diff --git a/android/cactus_jni.cpp b/android/cactus_jni.cpp index 75b322fbe..f9618c3d4 100644 --- a/android/cactus_jni.cpp +++ b/android/cactus_jni.cpp @@ -1,419 +1,490 @@ #include -#include -#include -#include -#include "cactus_engine.h" - -static constexpr size_t DEFAULT_BUFFER_SIZE = 65536; - -static const char* jstring_to_cstr(JNIEnv* env, jstring str) { - if (str == nullptr) return nullptr; - return env->GetStringUTFChars(str, nullptr); -} - -static void release_jstring(JNIEnv* env, jstring str, const char* cstr) { - if (str != nullptr && cstr != nullptr) { - env->ReleaseStringUTFChars(str, cstr); - } -} +#include "cactus.h" struct TokenCallbackContext { - JNIEnv* env; + JavaVM* jvm; + jobject callback; + jmethodID method; +}; + +struct LogCallbackContext { + JavaVM* jvm; jobject callback; jmethodID method; }; +static LogCallbackContext* g_log_callback_ctx = nullptr; + +extern "C" { + static void token_callback_bridge(const char* token, uint32_t token_id, void* user_data) { - if (!user_data) return; auto* ctx = static_cast(user_data); - jstring jtoken = ctx->env->NewStringUTF(token); - ctx->env->CallVoidMethod(ctx->callback, ctx->method, jtoken, static_cast(token_id)); - ctx->env->DeleteLocalRef(jtoken); + JNIEnv* env = nullptr; + bool attached = false; + jint status = ctx->jvm->GetEnv(reinterpret_cast(&env), JNI_VERSION_1_6); + if (status == JNI_EDETACHED) { + ctx->jvm->AttachCurrentThread(&env, nullptr); + attached = true; + } + jstring jtoken = env->NewStringUTF(token); + env->CallVoidMethod(ctx->callback, ctx->method, jtoken, static_cast(token_id)); + env->DeleteLocalRef(jtoken); + if (attached) ctx->jvm->DetachCurrentThread(); } -extern "C" { +static void log_callback_bridge(int level, const char* component, const char* message, void* user_data) { + auto* ctx = static_cast(user_data); + JNIEnv* env = nullptr; + bool attached = false; + jint status = ctx->jvm->GetEnv(reinterpret_cast(&env), JNI_VERSION_1_6); + if (status == JNI_EDETACHED) { + ctx->jvm->AttachCurrentThread(&env, nullptr); + attached = true; + } + jstring jcomponent = env->NewStringUTF(component); + jstring jmessage = env->NewStringUTF(message); + env->CallVoidMethod(ctx->callback, ctx->method, static_cast(level), jcomponent, jmessage); + env->DeleteLocalRef(jcomponent); + env->DeleteLocalRef(jmessage); + if (attached) ctx->jvm->DetachCurrentThread(); +} JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM*, void*) { - cactus_set_telemetry_environment("kotlin", nullptr, nullptr); return JNI_VERSION_1_6; } -JNIEXPORT void JNICALL -Java_com_cactus_Cactus_nativeSetCacheDir(JNIEnv* env, jobject, jstring cacheDir) { - const char* dir = jstring_to_cstr(env, cacheDir); - cactus_set_telemetry_environment(nullptr, dir, nullptr); - release_jstring(env, cacheDir, dir); -} - JNIEXPORT jlong JNICALL -Java_com_cactus_Cactus_nativeInit(JNIEnv* env, jobject, jstring modelPath, jstring corpusDir) { - const char* path = jstring_to_cstr(env, modelPath); - const char* corpus = jstring_to_cstr(env, corpusDir); - jlong handle = reinterpret_cast(cactus_init(path, corpus, false)); - release_jstring(env, modelPath, path); - release_jstring(env, corpusDir, corpus); +Java_com_cactus_CactusJNI_nativeInit(JNIEnv* env, jobject, jstring modelPath, jstring corpusDir, jboolean cacheIndex) { + const char* path = env->GetStringUTFChars(modelPath, nullptr); + const char* corpus = corpusDir ? env->GetStringUTFChars(corpusDir, nullptr) : nullptr; + jlong handle = reinterpret_cast(cactus_init(path, corpus, cacheIndex == JNI_TRUE)); + env->ReleaseStringUTFChars(modelPath, path); + if (corpus) env->ReleaseStringUTFChars(corpusDir, corpus); return handle; } JNIEXPORT void JNICALL -Java_com_cactus_Cactus_nativeDestroy(JNIEnv*, jobject, jlong handle) { - if (handle != 0) { - cactus_destroy(reinterpret_cast(handle)); - } +Java_com_cactus_CactusJNI_nativeDestroy(JNIEnv*, jobject, jlong handle) { + cactus_destroy(reinterpret_cast(handle)); } JNIEXPORT void JNICALL -Java_com_cactus_Cactus_nativeReset(JNIEnv*, jobject, jlong handle) { - if (handle != 0) { - cactus_reset(reinterpret_cast(handle)); - } +Java_com_cactus_CactusJNI_nativeReset(JNIEnv*, jobject, jlong handle) { + cactus_reset(reinterpret_cast(handle)); } JNIEXPORT void JNICALL -Java_com_cactus_Cactus_nativeStop(JNIEnv*, jobject, jlong handle) { - if (handle != 0) { - cactus_stop(reinterpret_cast(handle)); - } +Java_com_cactus_CactusJNI_nativeStop(JNIEnv*, jobject, jlong handle) { + cactus_stop(reinterpret_cast(handle)); } -JNIEXPORT jstring JNICALL -Java_com_cactus_Cactus_nativeComplete(JNIEnv* env, jobject, jlong handle, - jstring messagesJson, jstring optionsJson, - jstring toolsJson, jobject callback) { - if (handle == 0) { - return env->NewStringUTF("{\"error\":\"Model not initialized\"}"); - } - - const char* messages = jstring_to_cstr(env, messagesJson); - const char* options = jstring_to_cstr(env, optionsJson); - const char* tools = jstring_to_cstr(env, toolsJson); +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeComplete(JNIEnv* env, jobject, jlong handle, + jstring messagesJson, jbyteArray responseBuffer, + jstring optionsJson, jstring toolsJson, + jobject callback, jbyteArray pcmData) { + const char* messages = env->GetStringUTFChars(messagesJson, nullptr); + const char* options = optionsJson ? env->GetStringUTFChars(optionsJson, nullptr) : nullptr; + const char* tools = toolsJson ? env->GetStringUTFChars(toolsJson, nullptr) : nullptr; - std::vector buffer(DEFAULT_BUFFER_SIZE); + jsize bufSize = env->GetArrayLength(responseBuffer); + jbyte* buf = env->GetByteArrayElements(responseBuffer, nullptr); TokenCallbackContext* ctx = nullptr; cactus_token_callback cb = nullptr; + if (callback) { + JavaVM* jvm = nullptr; + env->GetJavaVM(&jvm); + jclass cls = env->GetObjectClass(callback); + jmethodID method = env->GetMethodID(cls, "onToken", "(Ljava/lang/String;I)V"); + ctx = new TokenCallbackContext{jvm, env->NewGlobalRef(callback), method}; + cb = token_callback_bridge; + } - if (callback != nullptr) { - jclass callbackClass = env->GetObjectClass(callback); - jmethodID method = env->GetMethodID(callbackClass, "onToken", "(Ljava/lang/String;I)V"); - if (method != nullptr) { - ctx = new TokenCallbackContext{env, callback, method}; - cb = token_callback_bridge; - } + jbyte* pcmBytes = nullptr; + size_t pcmSize = 0; + if (pcmData) { + pcmSize = env->GetArrayLength(pcmData); + pcmBytes = env->GetByteArrayElements(pcmData, nullptr); } int result = cactus_complete( reinterpret_cast(handle), - messages, - buffer.data(), - buffer.size(), - options, - tools, - cb, - ctx, - nullptr, - 0 + messages, reinterpret_cast(buf), static_cast(bufSize), + options, tools, cb, ctx, + reinterpret_cast(pcmBytes), pcmSize ); - delete ctx; - - release_jstring(env, messagesJson, messages); - release_jstring(env, optionsJson, options); - release_jstring(env, toolsJson, tools); - - if (result < 0) { - const char* error = cactus_get_last_error(); - std::string errorJson = "{\"error\":\"" + std::string(error ? error : "Unknown error") + "\"}"; - return env->NewStringUTF(errorJson.c_str()); - } + if (ctx) { env->DeleteGlobalRef(ctx->callback); delete ctx; } + env->ReleaseByteArrayElements(responseBuffer, buf, 0); + if (pcmBytes) env->ReleaseByteArrayElements(pcmData, pcmBytes, JNI_ABORT); + env->ReleaseStringUTFChars(messagesJson, messages); + if (options) env->ReleaseStringUTFChars(optionsJson, options); + if (tools) env->ReleaseStringUTFChars(toolsJson, tools); - return env->NewStringUTF(buffer.data()); + return result; } -JNIEXPORT jstring JNICALL -Java_com_cactus_Cactus_nativeTranscribe(JNIEnv* env, jobject, jlong handle, - jstring audioPath, jstring prompt, - jstring optionsJson, jbyteArray pcmData) { - if (handle == 0) { - return env->NewStringUTF("{\"error\":\"Model not initialized\"}"); - } - - const char* path = jstring_to_cstr(env, audioPath); - const char* promptStr = jstring_to_cstr(env, prompt); - const char* options = jstring_to_cstr(env, optionsJson); +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativePrefill(JNIEnv* env, jobject, jlong handle, + jstring messagesJson, jbyteArray responseBuffer, + jstring optionsJson, jstring toolsJson, + jbyteArray pcmData) { + const char* messages = env->GetStringUTFChars(messagesJson, nullptr); + const char* options = optionsJson ? env->GetStringUTFChars(optionsJson, nullptr) : nullptr; + const char* tools = toolsJson ? env->GetStringUTFChars(toolsJson, nullptr) : nullptr; - std::vector buffer(DEFAULT_BUFFER_SIZE); + jsize bufSize = env->GetArrayLength(responseBuffer); + jbyte* buf = env->GetByteArrayElements(responseBuffer, nullptr); - const uint8_t* pcmBuffer = nullptr; - size_t pcmSize = 0; jbyte* pcmBytes = nullptr; - - if (pcmData != nullptr) { + size_t pcmSize = 0; + if (pcmData) { pcmSize = env->GetArrayLength(pcmData); pcmBytes = env->GetByteArrayElements(pcmData, nullptr); - pcmBuffer = reinterpret_cast(pcmBytes); } - int result = cactus_transcribe( + int result = cactus_prefill( reinterpret_cast(handle), - path, - promptStr, - buffer.data(), - buffer.size(), - options, - nullptr, - nullptr, - pcmBuffer, - pcmSize + messages, reinterpret_cast(buf), static_cast(bufSize), + options, tools, + reinterpret_cast(pcmBytes), pcmSize ); - if (pcmBytes != nullptr) { - env->ReleaseByteArrayElements(pcmData, pcmBytes, JNI_ABORT); - } + env->ReleaseByteArrayElements(responseBuffer, buf, 0); + if (pcmBytes) env->ReleaseByteArrayElements(pcmData, pcmBytes, JNI_ABORT); + env->ReleaseStringUTFChars(messagesJson, messages); + if (options) env->ReleaseStringUTFChars(optionsJson, options); + if (tools) env->ReleaseStringUTFChars(toolsJson, tools); - release_jstring(env, audioPath, path); - release_jstring(env, prompt, promptStr); - release_jstring(env, optionsJson, options); + return result; +} - if (result < 0) { - const char* error = cactus_get_last_error(); - std::string errorJson = "{\"error\":\"" + std::string(error ? error : "Unknown error") + "\"}"; - return env->NewStringUTF(errorJson.c_str()); - } +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeTokenize(JNIEnv* env, jobject, jlong handle, + jstring text, jintArray tokenBuffer, jlongArray outTokenLen) { + const char* textStr = env->GetStringUTFChars(text, nullptr); + jsize bufLen = env->GetArrayLength(tokenBuffer); + jint* tokens = env->GetIntArrayElements(tokenBuffer, nullptr); + size_t tokenLen = 0; - return env->NewStringUTF(buffer.data()); -} + int result = cactus_tokenize( + reinterpret_cast(handle), + textStr, + reinterpret_cast(tokens), + static_cast(bufLen), + &tokenLen + ); -JNIEXPORT jfloatArray JNICALL -Java_com_cactus_Cactus_nativeEmbed(JNIEnv* env, jobject, jlong handle, - jstring text, jboolean normalize) { - if (handle == 0) { - return nullptr; - } + env->ReleaseIntArrayElements(tokenBuffer, tokens, 0); + env->ReleaseStringUTFChars(text, textStr); - const char* textStr = jstring_to_cstr(env, text); + jlong len = static_cast(tokenLen); + env->SetLongArrayRegion(outTokenLen, 0, 1, &len); - std::vector buffer(4096); - size_t embeddingDim = 0; + return result; +} - int result = cactus_embed( +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeScoreWindow(JNIEnv* env, jobject, jlong handle, + jintArray tokens, jlong start, jlong end, + jlong context, jbyteArray responseBuffer) { + jsize tokenLen = env->GetArrayLength(tokens); + jint* tokenData = env->GetIntArrayElements(tokens, nullptr); + jsize bufSize = env->GetArrayLength(responseBuffer); + jbyte* buf = env->GetByteArrayElements(responseBuffer, nullptr); + + int result = cactus_score_window( reinterpret_cast(handle), - textStr, - buffer.data(), - buffer.size(), - &embeddingDim, - normalize == JNI_TRUE + reinterpret_cast(tokenData), + static_cast(tokenLen), + static_cast(start), + static_cast(end), + static_cast(context), + reinterpret_cast(buf), + static_cast(bufSize) ); - release_jstring(env, text, textStr); + env->ReleaseIntArrayElements(tokens, tokenData, JNI_ABORT); + env->ReleaseByteArrayElements(responseBuffer, buf, 0); - if (result < 0 || embeddingDim == 0) { - return nullptr; - } + return result; +} - jfloatArray jarray = env->NewFloatArray(static_cast(embeddingDim)); - env->SetFloatArrayRegion(jarray, 0, static_cast(embeddingDim), buffer.data()); +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeTranscribe(JNIEnv* env, jobject, jlong handle, + jstring audioPath, jstring prompt, + jbyteArray responseBuffer, + jstring optionsJson, jobject callback, + jbyteArray pcmData) { + const char* path = audioPath ? env->GetStringUTFChars(audioPath, nullptr) : nullptr; + const char* promptStr = env->GetStringUTFChars(prompt, nullptr); + const char* options = optionsJson ? env->GetStringUTFChars(optionsJson, nullptr) : nullptr; + + jsize bufSize = env->GetArrayLength(responseBuffer); + jbyte* buf = env->GetByteArrayElements(responseBuffer, nullptr); - return jarray; -} + TokenCallbackContext* ctx = nullptr; + cactus_token_callback cb = nullptr; + if (callback) { + JavaVM* jvm = nullptr; + env->GetJavaVM(&jvm); + jclass cls = env->GetObjectClass(callback); + jmethodID method = env->GetMethodID(cls, "onToken", "(Ljava/lang/String;I)V"); + ctx = new TokenCallbackContext{jvm, env->NewGlobalRef(callback), method}; + cb = token_callback_bridge; + } -JNIEXPORT jstring JNICALL -Java_com_cactus_Cactus_nativeRagQuery(JNIEnv* env, jobject, jlong handle, - jstring query, jint topK) { - if (handle == 0) { - return env->NewStringUTF("{\"error\":\"Model not initialized\"}"); + jbyte* pcmBytes = nullptr; + size_t pcmSize = 0; + if (pcmData) { + pcmSize = env->GetArrayLength(pcmData); + pcmBytes = env->GetByteArrayElements(pcmData, nullptr); } - const char* queryStr = jstring_to_cstr(env, query); + int result = cactus_transcribe( + reinterpret_cast(handle), + path, promptStr, + reinterpret_cast(buf), static_cast(bufSize), + options, cb, ctx, + reinterpret_cast(pcmBytes), pcmSize + ); - std::vector buffer(DEFAULT_BUFFER_SIZE); + if (ctx) { env->DeleteGlobalRef(ctx->callback); delete ctx; } + env->ReleaseByteArrayElements(responseBuffer, buf, 0); + if (pcmBytes) env->ReleaseByteArrayElements(pcmData, pcmBytes, JNI_ABORT); + if (path) env->ReleaseStringUTFChars(audioPath, path); + env->ReleaseStringUTFChars(prompt, promptStr); + if (options) env->ReleaseStringUTFChars(optionsJson, options); - int result = cactus_rag_query( + return result; +} + +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeEmbed(JNIEnv* env, jobject, jlong handle, + jstring text, jfloatArray embeddingsBuffer, + jlongArray outEmbeddingDim, jboolean normalize) { + const char* textStr = env->GetStringUTFChars(text, nullptr); + jsize bufSize = env->GetArrayLength(embeddingsBuffer); + jfloat* buf = env->GetFloatArrayElements(embeddingsBuffer, nullptr); + size_t embeddingDim = 0; + + int result = cactus_embed( reinterpret_cast(handle), - queryStr, - buffer.data(), - buffer.size(), - static_cast(topK) + textStr, buf, static_cast(bufSize), + &embeddingDim, normalize == JNI_TRUE ); - release_jstring(env, query, queryStr); + env->ReleaseFloatArrayElements(embeddingsBuffer, buf, 0); + env->ReleaseStringUTFChars(text, textStr); - if (result < 0) { - const char* error = cactus_get_last_error(); - std::string errorJson = "{\"error\":\"" + std::string(error ? error : "Unknown error") + "\"}"; - return env->NewStringUTF(errorJson.c_str()); - } + jlong dim = static_cast(embeddingDim); + env->SetLongArrayRegion(outEmbeddingDim, 0, 1, &dim); - return env->NewStringUTF(buffer.data()); + return result; } -JNIEXPORT jstring JNICALL -Java_com_cactus_Cactus_nativeGetLastError(JNIEnv* env, jobject) { - const char* error = cactus_get_last_error(); - return env->NewStringUTF(error ? error : ""); -} +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeImageEmbed(JNIEnv* env, jobject, jlong handle, + jstring imagePath, jfloatArray embeddingsBuffer, + jlongArray outEmbeddingDim) { + const char* path = env->GetStringUTFChars(imagePath, nullptr); + jsize bufSize = env->GetArrayLength(embeddingsBuffer); + jfloat* buf = env->GetFloatArrayElements(embeddingsBuffer, nullptr); + size_t embeddingDim = 0; -JNIEXPORT jintArray JNICALL -Java_com_cactus_Cactus_nativeTokenize(JNIEnv* env, jobject, jlong handle, jstring text) { - if (handle == 0) return nullptr; + int result = cactus_image_embed( + reinterpret_cast(handle), + path, buf, static_cast(bufSize), &embeddingDim + ); - const char* textStr = jstring_to_cstr(env, text); - std::vector buffer(8192); - size_t tokenLen = 0; + env->ReleaseFloatArrayElements(embeddingsBuffer, buf, 0); + env->ReleaseStringUTFChars(imagePath, path); - int result = cactus_tokenize( + jlong dim = static_cast(embeddingDim); + env->SetLongArrayRegion(outEmbeddingDim, 0, 1, &dim); + + return result; +} + +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeAudioEmbed(JNIEnv* env, jobject, jlong handle, + jstring audioPath, jfloatArray embeddingsBuffer, + jlongArray outEmbeddingDim) { + const char* path = env->GetStringUTFChars(audioPath, nullptr); + jsize bufSize = env->GetArrayLength(embeddingsBuffer); + jfloat* buf = env->GetFloatArrayElements(embeddingsBuffer, nullptr); + size_t embeddingDim = 0; + + int result = cactus_audio_embed( reinterpret_cast(handle), - textStr, - buffer.data(), - buffer.size(), - &tokenLen + path, buf, static_cast(bufSize), &embeddingDim ); - release_jstring(env, text, textStr); + env->ReleaseFloatArrayElements(embeddingsBuffer, buf, 0); + env->ReleaseStringUTFChars(audioPath, path); - if (result < 0 || tokenLen == 0) return nullptr; + jlong dim = static_cast(embeddingDim); + env->SetLongArrayRegion(outEmbeddingDim, 0, 1, &dim); - jintArray jarray = env->NewIntArray(static_cast(tokenLen)); - env->SetIntArrayRegion(jarray, 0, static_cast(tokenLen), reinterpret_cast(buffer.data())); - return jarray; + return result; } -JNIEXPORT jstring JNICALL -Java_com_cactus_Cactus_nativeScoreWindow(JNIEnv* env, jobject, jlong handle, - jintArray tokens, jint start, jint end, jint context) { - if (handle == 0) return env->NewStringUTF("{\"error\":\"Model not initialized\"}"); +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeVad(JNIEnv* env, jobject, jlong handle, + jstring audioPath, jbyteArray responseBuffer, + jstring optionsJson, jbyteArray pcmData) { + const char* path = audioPath ? env->GetStringUTFChars(audioPath, nullptr) : nullptr; + const char* options = optionsJson ? env->GetStringUTFChars(optionsJson, nullptr) : nullptr; - jsize tokenLen = env->GetArrayLength(tokens); - jint* tokenData = env->GetIntArrayElements(tokens, nullptr); + jsize bufSize = env->GetArrayLength(responseBuffer); + jbyte* buf = env->GetByteArrayElements(responseBuffer, nullptr); - std::vector buffer(DEFAULT_BUFFER_SIZE); + jbyte* pcmBytes = nullptr; + size_t pcmSize = 0; + if (pcmData) { + pcmSize = env->GetArrayLength(pcmData); + pcmBytes = env->GetByteArrayElements(pcmData, nullptr); + } - int result = cactus_score_window( + int result = cactus_vad( reinterpret_cast(handle), - reinterpret_cast(tokenData), - static_cast(tokenLen), - static_cast(start), - static_cast(end), - static_cast(context), - buffer.data(), - buffer.size() + path, reinterpret_cast(buf), static_cast(bufSize), + options, + reinterpret_cast(pcmBytes), pcmSize ); - env->ReleaseIntArrayElements(tokens, tokenData, JNI_ABORT); + env->ReleaseByteArrayElements(responseBuffer, buf, 0); + if (pcmBytes) env->ReleaseByteArrayElements(pcmData, pcmBytes, JNI_ABORT); + if (path) env->ReleaseStringUTFChars(audioPath, path); + if (options) env->ReleaseStringUTFChars(optionsJson, options); - if (result < 0) { - const char* error = cactus_get_last_error(); - std::string errorJson = "{\"error\":\"" + std::string(error ? error : "Unknown error") + "\"}"; - return env->NewStringUTF(errorJson.c_str()); + return result; +} + +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeDiarize(JNIEnv* env, jobject, jlong handle, + jstring audioPath, jbyteArray responseBuffer, + jstring optionsJson, jbyteArray pcmData) { + const char* path = audioPath ? env->GetStringUTFChars(audioPath, nullptr) : nullptr; + const char* options = optionsJson ? env->GetStringUTFChars(optionsJson, nullptr) : nullptr; + + jsize bufSize = env->GetArrayLength(responseBuffer); + jbyte* buf = env->GetByteArrayElements(responseBuffer, nullptr); + + jbyte* pcmBytes = nullptr; + size_t pcmSize = 0; + if (pcmData) { + pcmSize = env->GetArrayLength(pcmData); + pcmBytes = env->GetByteArrayElements(pcmData, nullptr); } - return env->NewStringUTF(buffer.data()); -} + int result = cactus_diarize( + reinterpret_cast(handle), + path, reinterpret_cast(buf), static_cast(bufSize), + options, + reinterpret_cast(pcmBytes), pcmSize + ); -JNIEXPORT jlong JNICALL -Java_com_cactus_Cactus_nativeStreamTranscribeInit(JNIEnv*, jobject, jlong /*handle*/) { - return 0; -} + env->ReleaseByteArrayElements(responseBuffer, buf, 0); + if (pcmBytes) env->ReleaseByteArrayElements(pcmData, pcmBytes, JNI_ABORT); + if (path) env->ReleaseStringUTFChars(audioPath, path); + if (options) env->ReleaseStringUTFChars(optionsJson, options); -JNIEXPORT jstring JNICALL -Java_com_cactus_Cactus_nativeStreamTranscribeProcess(JNIEnv* env, jobject, jlong /*streamHandle*/, jbyteArray /*pcmData*/) { - return env->NewStringUTF("{\"error\":\"stream transcribe not implemented\"}"); + return result; } -JNIEXPORT jstring JNICALL -Java_com_cactus_Cactus_nativeStreamTranscribeStop(JNIEnv* env, jobject, jlong /*streamHandle*/) { - return env->NewStringUTF("{\"error\":\"stream transcribe not implemented\"}"); -} +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeEmbedSpeaker(JNIEnv* env, jobject, jlong handle, + jstring audioPath, jbyteArray responseBuffer, + jstring optionsJson, jbyteArray pcmData, + jfloatArray maskWeights, jlong maskNumFrames) { + const char* path = audioPath ? env->GetStringUTFChars(audioPath, nullptr) : nullptr; + const char* options = optionsJson ? env->GetStringUTFChars(optionsJson, nullptr) : nullptr; -JNIEXPORT jfloatArray JNICALL -Java_com_cactus_Cactus_nativeImageEmbed(JNIEnv* env, jobject, jlong handle, jstring imagePath) { - if (handle == 0) return nullptr; + jsize bufSize = env->GetArrayLength(responseBuffer); + jbyte* buf = env->GetByteArrayElements(responseBuffer, nullptr); - const char* path = jstring_to_cstr(env, imagePath); - std::vector buffer(4096); - size_t embeddingDim = 0; + jbyte* pcmBytes = nullptr; + size_t pcmSize = 0; + if (pcmData) { + pcmSize = env->GetArrayLength(pcmData); + pcmBytes = env->GetByteArrayElements(pcmData, nullptr); + } - int result = cactus_image_embed( + jfloat* maskPtr = nullptr; + if (maskWeights) { + maskPtr = env->GetFloatArrayElements(maskWeights, nullptr); + } + + int result = cactus_embed_speaker( reinterpret_cast(handle), - path, - buffer.data(), - buffer.size(), - &embeddingDim + path, reinterpret_cast(buf), static_cast(bufSize), + options, + reinterpret_cast(pcmBytes), pcmSize, + maskPtr, static_cast(maskNumFrames) ); - release_jstring(env, imagePath, path); - - if (result < 0 || embeddingDim == 0) return nullptr; + env->ReleaseByteArrayElements(responseBuffer, buf, 0); + if (maskPtr) env->ReleaseFloatArrayElements(maskWeights, maskPtr, JNI_ABORT); + if (pcmBytes) env->ReleaseByteArrayElements(pcmData, pcmBytes, JNI_ABORT); + if (path) env->ReleaseStringUTFChars(audioPath, path); + if (options) env->ReleaseStringUTFChars(optionsJson, options); - jfloatArray jarray = env->NewFloatArray(static_cast(embeddingDim)); - env->SetFloatArrayRegion(jarray, 0, static_cast(embeddingDim), buffer.data()); - return jarray; + return result; } -JNIEXPORT jfloatArray JNICALL -Java_com_cactus_Cactus_nativeAudioEmbed(JNIEnv* env, jobject, jlong handle, jstring audioPath) { - if (handle == 0) return nullptr; - - const char* path = jstring_to_cstr(env, audioPath); - std::vector buffer(4096); - size_t embeddingDim = 0; +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeRagQuery(JNIEnv* env, jobject, jlong handle, + jstring query, jbyteArray responseBuffer, jlong topK) { + const char* queryStr = env->GetStringUTFChars(query, nullptr); + jsize bufSize = env->GetArrayLength(responseBuffer); + jbyte* buf = env->GetByteArrayElements(responseBuffer, nullptr); - int result = cactus_audio_embed( + int result = cactus_rag_query( reinterpret_cast(handle), - path, - buffer.data(), - buffer.size(), - &embeddingDim + queryStr, reinterpret_cast(buf), static_cast(bufSize), + static_cast(topK) ); - release_jstring(env, audioPath, path); - - if (result < 0 || embeddingDim == 0) return nullptr; + env->ReleaseByteArrayElements(responseBuffer, buf, 0); + env->ReleaseStringUTFChars(query, queryStr); - jfloatArray jarray = env->NewFloatArray(static_cast(embeddingDim)); - env->SetFloatArrayRegion(jarray, 0, static_cast(embeddingDim), buffer.data()); - return jarray; -} - -JNIEXPORT jstring JNICALL -Java_com_cactus_Cactus_nativeVad(JNIEnv* env, jobject, jlong /*handle*/, - jstring /*audioPath*/, jstring /*optionsJson*/, jbyteArray /*pcmData*/) { - return env->NewStringUTF("{\"error\":\"VAD not implemented\"}"); + return result; } JNIEXPORT jlong JNICALL -Java_com_cactus_CactusIndex_nativeIndexInit(JNIEnv* env, jobject, jstring indexDir, jint embeddingDim) { - const char* dir = jstring_to_cstr(env, indexDir); +Java_com_cactus_CactusJNI_nativeIndexInit(JNIEnv* env, jobject, jstring indexDir, jlong embeddingDim) { + const char* dir = env->GetStringUTFChars(indexDir, nullptr); jlong handle = reinterpret_cast(cactus_index_init(dir, static_cast(embeddingDim))); - release_jstring(env, indexDir, dir); + env->ReleaseStringUTFChars(indexDir, dir); return handle; } JNIEXPORT jint JNICALL -Java_com_cactus_CactusIndex_nativeIndexAdd(JNIEnv* env, jobject, jlong handle, - jintArray ids, jobjectArray documents, - jobjectArray metadatas, jobjectArray embeddings, - jint embeddingDim) { - if (handle == 0) return -1; - +Java_com_cactus_CactusJNI_nativeIndexAdd(JNIEnv* env, jobject, jlong handle, + jintArray ids, jobjectArray documents, + jobjectArray metadatas, jobjectArray embeddings, + jlong embeddingDim) { jsize count = env->GetArrayLength(ids); jint* idData = env->GetIntArrayElements(ids, nullptr); - std::vector docPtrs(count); - std::vector metaPtrs(count); - std::vector embPtrs(count); - std::vector docStrings(count); - std::vector metaStrings(count); - std::vector embArrays(count); + const char** docPtrs = new const char*[count]; + const char** metaPtrs = new const char*[count]; + const float** embPtrs = new const float*[count]; + jstring* docStrings = new jstring[count]; + jstring* metaStrings = new jstring[count]; + jfloatArray* embArrays = new jfloatArray[count]; for (jsize i = 0; i < count; i++) { docStrings[i] = static_cast(env->GetObjectArrayElement(documents, i)); - docPtrs[i] = jstring_to_cstr(env, docStrings[i]); + docPtrs[i] = env->GetStringUTFChars(docStrings[i], nullptr); - if (metadatas != nullptr) { + if (metadatas) { metaStrings[i] = static_cast(env->GetObjectArrayElement(metadatas, i)); - metaPtrs[i] = jstring_to_cstr(env, metaStrings[i]); + metaPtrs[i] = env->GetStringUTFChars(metaStrings[i], nullptr); } else { + metaStrings[i] = nullptr; metaPtrs[i] = nullptr; } @@ -424,29 +495,31 @@ Java_com_cactus_CactusIndex_nativeIndexAdd(JNIEnv* env, jobject, jlong handle, int result = cactus_index_add( reinterpret_cast(handle), reinterpret_cast(idData), - docPtrs.data(), - metadatas != nullptr ? metaPtrs.data() : nullptr, - embPtrs.data(), - static_cast(count), - static_cast(embeddingDim) + docPtrs, metadatas ? metaPtrs : nullptr, embPtrs, + static_cast(count), static_cast(embeddingDim) ); for (jsize i = 0; i < count; i++) { - release_jstring(env, docStrings[i], docPtrs[i]); - if (metadatas != nullptr) { - release_jstring(env, metaStrings[i], metaPtrs[i]); - } + env->ReleaseStringUTFChars(docStrings[i], docPtrs[i]); + env->DeleteLocalRef(docStrings[i]); + if (metaStrings[i]) { env->ReleaseStringUTFChars(metaStrings[i], metaPtrs[i]); env->DeleteLocalRef(metaStrings[i]); } env->ReleaseFloatArrayElements(embArrays[i], const_cast(embPtrs[i]), JNI_ABORT); + env->DeleteLocalRef(embArrays[i]); } env->ReleaseIntArrayElements(ids, idData, JNI_ABORT); + delete[] docPtrs; + delete[] metaPtrs; + delete[] embPtrs; + delete[] docStrings; + delete[] metaStrings; + delete[] embArrays; + return result; } JNIEXPORT jint JNICALL -Java_com_cactus_CactusIndex_nativeIndexDelete(JNIEnv* env, jobject, jlong handle, jintArray ids) { - if (handle == 0) return -1; - +Java_com_cactus_CactusJNI_nativeIndexDelete(JNIEnv* env, jobject, jlong handle, jintArray ids) { jsize count = env->GetArrayLength(ids); jint* idData = env->GetIntArrayElements(ids, nullptr); @@ -460,66 +533,218 @@ Java_com_cactus_CactusIndex_nativeIndexDelete(JNIEnv* env, jobject, jlong handle return result; } -JNIEXPORT jstring JNICALL -Java_com_cactus_CactusIndex_nativeIndexQuery(JNIEnv* env, jobject, jlong handle, - jfloatArray embedding, jint topK, jstring optionsJson) { - if (handle == 0) return env->NewStringUTF("{\"error\":\"Index not initialized\"}"); +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeIndexGet(JNIEnv* env, jobject, jlong handle, + jintArray ids, + jobjectArray documentBuffers, jlongArray documentBufferSizes, + jobjectArray metadataBuffers, jlongArray metadataBufferSizes, + jobjectArray embeddingBuffers, jlongArray embeddingBufferSizes) { + jsize count = env->GetArrayLength(ids); + jint* idData = env->GetIntArrayElements(ids, nullptr); - jsize embDim = env->GetArrayLength(embedding); - jfloat* embData = env->GetFloatArrayElements(embedding, nullptr); - const char* options = jstring_to_cstr(env, optionsJson); + char** docBufs = new char*[count]; + size_t* docSizes = new size_t[count]; + char** metaBufs = new char*[count]; + size_t* metaSizes = new size_t[count]; + float** embBufs = new float*[count]; + size_t* embSizes = new size_t[count]; - std::vector idBuffer(topK); - std::vector scoreBuffer(topK); - size_t idBufferSize = topK; - size_t scoreBufferSize = topK; + jbyteArray* docArrays = new jbyteArray[count]; + jbyteArray* metaArrays = new jbyteArray[count]; + jfloatArray* embArrays = new jfloatArray[count]; - const float* embPtr = embData; - int* idPtr = idBuffer.data(); - float* scorePtr = scoreBuffer.data(); + jlong* docSizesIn = env->GetLongArrayElements(documentBufferSizes, nullptr); + jlong* metaSizesIn = env->GetLongArrayElements(metadataBufferSizes, nullptr); + jlong* embSizesIn = env->GetLongArrayElements(embeddingBufferSizes, nullptr); - int result = cactus_index_query( + for (jsize i = 0; i < count; i++) { + docArrays[i] = static_cast(env->GetObjectArrayElement(documentBuffers, i)); + docBufs[i] = reinterpret_cast(env->GetByteArrayElements(docArrays[i], nullptr)); + docSizes[i] = static_cast(docSizesIn[i]); + + metaArrays[i] = static_cast(env->GetObjectArrayElement(metadataBuffers, i)); + metaBufs[i] = reinterpret_cast(env->GetByteArrayElements(metaArrays[i], nullptr)); + metaSizes[i] = static_cast(metaSizesIn[i]); + + embArrays[i] = static_cast(env->GetObjectArrayElement(embeddingBuffers, i)); + embBufs[i] = env->GetFloatArrayElements(embArrays[i], nullptr); + embSizes[i] = static_cast(embSizesIn[i]); + } + + int result = cactus_index_get( reinterpret_cast(handle), - &embPtr, - 1, - static_cast(embDim), - options, - &idPtr, - &idBufferSize, - &scorePtr, - &scoreBufferSize + reinterpret_cast(idData), + static_cast(count), + docBufs, docSizes, metaBufs, metaSizes, embBufs, embSizes ); - env->ReleaseFloatArrayElements(embedding, embData, JNI_ABORT); - release_jstring(env, optionsJson, options); + for (jsize i = 0; i < count; i++) { + env->ReleaseByteArrayElements(docArrays[i], reinterpret_cast(docBufs[i]), 0); + env->DeleteLocalRef(docArrays[i]); + env->ReleaseByteArrayElements(metaArrays[i], reinterpret_cast(metaBufs[i]), 0); + env->DeleteLocalRef(metaArrays[i]); + env->ReleaseFloatArrayElements(embArrays[i], embBufs[i], 0); + env->DeleteLocalRef(embArrays[i]); + docSizesIn[i] = static_cast(docSizes[i]); + metaSizesIn[i] = static_cast(metaSizes[i]); + embSizesIn[i] = static_cast(embSizes[i]); + } + + env->ReleaseLongArrayElements(documentBufferSizes, docSizesIn, 0); + env->ReleaseLongArrayElements(metadataBufferSizes, metaSizesIn, 0); + env->ReleaseLongArrayElements(embeddingBufferSizes, embSizesIn, 0); + env->ReleaseIntArrayElements(ids, idData, JNI_ABORT); + + delete[] docBufs; + delete[] docSizes; + delete[] metaBufs; + delete[] metaSizes; + delete[] embBufs; + delete[] embSizes; + delete[] docArrays; + delete[] metaArrays; + delete[] embArrays; + + return result; +} + +JNIEXPORT jint JNICALL +Java_com_cactus_CactusJNI_nativeIndexQuery(JNIEnv* env, jobject, jlong handle, + jobjectArray embeddings, jlong embeddingDim, + jstring optionsJson, + jobjectArray idBuffers, jlongArray idBufferSizes, + jobjectArray scoreBuffers, jlongArray scoreBufferSizes) { + jsize embCount = env->GetArrayLength(embeddings); + const char* options = optionsJson ? env->GetStringUTFChars(optionsJson, nullptr) : nullptr; + + const float** embPtrs = new const float*[embCount]; + jfloatArray* embArrays = new jfloatArray[embCount]; + + for (jsize i = 0; i < embCount; i++) { + embArrays[i] = static_cast(env->GetObjectArrayElement(embeddings, i)); + embPtrs[i] = env->GetFloatArrayElements(embArrays[i], nullptr); + } + + int** idPtrs = new int*[embCount]; + size_t* idSizes = new size_t[embCount]; + float** scorePtrs = new float*[embCount]; + size_t* scoreSizes = new size_t[embCount]; + + jintArray* idJArrays = new jintArray[embCount]; + jfloatArray* scoreJArrays = new jfloatArray[embCount]; + + jlong* idSizesIn = env->GetLongArrayElements(idBufferSizes, nullptr); + jlong* scoreSizesIn = env->GetLongArrayElements(scoreBufferSizes, nullptr); - if (result < 0) { - const char* error = cactus_get_last_error(); - std::string errorJson = "{\"error\":\"" + std::string(error ? error : "Unknown error") + "\"}"; - return env->NewStringUTF(errorJson.c_str()); + for (jsize i = 0; i < embCount; i++) { + idJArrays[i] = static_cast(env->GetObjectArrayElement(idBuffers, i)); + idPtrs[i] = env->GetIntArrayElements(idJArrays[i], nullptr); + idSizes[i] = static_cast(idSizesIn[i]); + + scoreJArrays[i] = static_cast(env->GetObjectArrayElement(scoreBuffers, i)); + scorePtrs[i] = env->GetFloatArrayElements(scoreJArrays[i], nullptr); + scoreSizes[i] = static_cast(scoreSizesIn[i]); } - std::string json = "{\"results\":["; - for (size_t i = 0; i < idBufferSize; i++) { - if (i > 0) json += ","; - json += "{\"id\":" + std::to_string(idBuffer[i]) + ",\"score\":" + std::to_string(scoreBuffer[i]) + "}"; + int result = cactus_index_query( + reinterpret_cast(handle), + embPtrs, static_cast(embCount), static_cast(embeddingDim), + options, idPtrs, idSizes, scorePtrs, scoreSizes + ); + + for (jsize i = 0; i < embCount; i++) { + env->ReleaseFloatArrayElements(embArrays[i], const_cast(embPtrs[i]), JNI_ABORT); + env->DeleteLocalRef(embArrays[i]); + env->ReleaseIntArrayElements(idJArrays[i], idPtrs[i], 0); + env->DeleteLocalRef(idJArrays[i]); + env->ReleaseFloatArrayElements(scoreJArrays[i], scorePtrs[i], 0); + env->DeleteLocalRef(scoreJArrays[i]); + idSizesIn[i] = static_cast(idSizes[i]); + scoreSizesIn[i] = static_cast(scoreSizes[i]); } - json += "]}"; - return env->NewStringUTF(json.c_str()); + env->ReleaseLongArrayElements(idBufferSizes, idSizesIn, 0); + env->ReleaseLongArrayElements(scoreBufferSizes, scoreSizesIn, 0); + if (options) env->ReleaseStringUTFChars(optionsJson, options); + + delete[] embPtrs; + delete[] embArrays; + delete[] idPtrs; + delete[] idSizes; + delete[] scorePtrs; + delete[] scoreSizes; + delete[] idJArrays; + delete[] scoreJArrays; + + return result; } JNIEXPORT jint JNICALL -Java_com_cactus_CactusIndex_nativeIndexCompact(JNIEnv*, jobject, jlong handle) { - if (handle == 0) return -1; +Java_com_cactus_CactusJNI_nativeIndexCompact(JNIEnv*, jobject, jlong handle) { return cactus_index_compact(reinterpret_cast(handle)); } JNIEXPORT void JNICALL -Java_com_cactus_CactusIndex_nativeIndexDestroy(JNIEnv*, jobject, jlong handle) { - if (handle != 0) { - cactus_index_destroy(reinterpret_cast(handle)); +Java_com_cactus_CactusJNI_nativeIndexDestroy(JNIEnv*, jobject, jlong handle) { + cactus_index_destroy(reinterpret_cast(handle)); +} + +JNIEXPORT jstring JNICALL +Java_com_cactus_CactusJNI_nativeGetLastError(JNIEnv* env, jobject) { + return env->NewStringUTF(cactus_get_last_error()); +} + +JNIEXPORT void JNICALL +Java_com_cactus_CactusJNI_nativeLogSetLevel(JNIEnv*, jobject, jint level) { + cactus_log_set_level(static_cast(level)); +} + +JNIEXPORT void JNICALL +Java_com_cactus_CactusJNI_nativeLogSetCallback(JNIEnv* env, jobject, jobject callback) { + if (g_log_callback_ctx) { + env->DeleteGlobalRef(g_log_callback_ctx->callback); + delete g_log_callback_ctx; + g_log_callback_ctx = nullptr; } + if (!callback) { + cactus_log_set_callback(nullptr, nullptr); + return; + } + JavaVM* jvm = nullptr; + env->GetJavaVM(&jvm); + jclass cls = env->GetObjectClass(callback); + jmethodID method = env->GetMethodID(cls, "onLog", "(ILjava/lang/String;Ljava/lang/String;)V"); + g_log_callback_ctx = new LogCallbackContext{jvm, env->NewGlobalRef(callback), method}; + cactus_log_set_callback(log_callback_bridge, g_log_callback_ctx); +} + +JNIEXPORT void JNICALL +Java_com_cactus_CactusJNI_nativeSetTelemetryEnvironment(JNIEnv* env, jobject, + jstring framework, jstring cacheLocation, jstring version) { + const char* fw = framework ? env->GetStringUTFChars(framework, nullptr) : nullptr; + const char* cache = cacheLocation ? env->GetStringUTFChars(cacheLocation, nullptr) : nullptr; + const char* ver = version ? env->GetStringUTFChars(version, nullptr) : nullptr; + cactus_set_telemetry_environment(fw, cache, ver); + if (fw) env->ReleaseStringUTFChars(framework, fw); + if (cache) env->ReleaseStringUTFChars(cacheLocation, cache); + if (ver) env->ReleaseStringUTFChars(version, ver); +} + +JNIEXPORT void JNICALL +Java_com_cactus_CactusJNI_nativeSetAppId(JNIEnv* env, jobject, jstring appId) { + const char* id = env->GetStringUTFChars(appId, nullptr); + cactus_set_app_id(id); + env->ReleaseStringUTFChars(appId, id); +} + +JNIEXPORT void JNICALL +Java_com_cactus_CactusJNI_nativeTelemetryFlush(JNIEnv*, jobject) { + cactus_telemetry_flush(); +} + +JNIEXPORT void JNICALL +Java_com_cactus_CactusJNI_nativeTelemetryShutdown(JNIEnv*, jobject) { + cactus_telemetry_shutdown(); } } diff --git a/apple/CMakeLists.txt b/apple/CMakeLists.txt new file mode 100644 index 000000000..531e253c8 --- /dev/null +++ b/apple/CMakeLists.txt @@ -0,0 +1,91 @@ +cmake_minimum_required(VERSION 3.10) +project(CactusApple LANGUAGES CXX) + +set(CMAKE_CXX_STANDARD 20) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +set(CMAKE_OSX_DEPLOYMENT_TARGET "13.0" CACHE STRING "Minimum macOS version") +set(CMAKE_XCODE_ATTRIBUTE_IPHONEOS_DEPLOYMENT_TARGET "13.0" CACHE STRING "Minimum iOS version") + +set(PROJECT_ROOT "${CMAKE_SOURCE_DIR}/..") + +if(NOT CMAKE_BUILD_TYPE) + set(CMAKE_BUILD_TYPE Release) +endif() + +set(CACTUS_ENGINE_DIR "${PROJECT_ROOT}/cactus-engine") +if(NOT TARGET cactus_engine) + add_subdirectory(${CACTUS_ENGINE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/cactus-engine) +endif() + +if(BUILD_SHARED_LIBS) + file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/empty.cpp" "") + add_library(cactus SHARED "${CMAKE_CURRENT_BINARY_DIR}/empty.cpp") + add_dependencies(cactus cactus_engine cactus_graph cactus_kernels) + + target_link_options(cactus PRIVATE + -force_load $ + -force_load $ + -force_load $ + ) + + find_library(COREML_FRAMEWORK CoreML REQUIRED) + find_library(FOUNDATION_FRAMEWORK Foundation REQUIRED) + find_library(ACCELERATE_FRAMEWORK Accelerate REQUIRED) + find_library(SECURITY_FRAMEWORK Security REQUIRED) + find_library(SYSTEMCONFIGURATION_FRAMEWORK SystemConfiguration REQUIRED) + find_library(CFNETWORK_FRAMEWORK CFNetwork REQUIRED) + target_link_libraries(cactus PUBLIC + ${COREML_FRAMEWORK} + ${FOUNDATION_FRAMEWORK} + ${ACCELERATE_FRAMEWORK} + ${SECURITY_FRAMEWORK} + ${SYSTEMCONFIGURATION_FRAMEWORK} + ${CFNETWORK_FRAMEWORK} + ) + + set(CACTUS_CURL_INCLUDE_DIR "${CACTUS_CURL_ROOT}/include") + if(CMAKE_SYSTEM_NAME STREQUAL "iOS") + string(TOLOWER "${CMAKE_OSX_SYSROOT}" _sysroot_lower) + if(_sysroot_lower MATCHES "simulator") + set(CACTUS_CURL_LIBRARY "${CACTUS_CURL_ROOT}/ios/simulator/libcurl.a") + else() + set(CACTUS_CURL_LIBRARY "${CACTUS_CURL_ROOT}/ios/device/libcurl.a") + endif() + else() + set(CACTUS_CURL_LIBRARY "${CACTUS_CURL_ROOT}/macos/libcurl.a") + endif() + if(EXISTS "${CACTUS_CURL_INCLUDE_DIR}/curl/curl.h" AND EXISTS "${CACTUS_CURL_LIBRARY}") + target_link_libraries(cactus PUBLIC "${CACTUS_CURL_LIBRARY}") + target_include_directories(cactus PUBLIC "${CACTUS_CURL_INCLUDE_DIR}") + endif() + + set_target_properties(cactus PROPERTIES + FRAMEWORK TRUE + FRAMEWORK_VERSION A + MACOSX_FRAMEWORK_IDENTIFIER com.cactuscompute.cactus + VERSION 1.0.0 + SOVERSION 1.0.0 + PUBLIC_HEADER "${CACTUS_ENGINE_DIR}/cactus_engine.h" + MACOSX_FRAMEWORK_INFO_PLIST "${CMAKE_SOURCE_DIR}/Info.plist" + ) + + if(CMAKE_SYSTEM_NAME STREQUAL "iOS") + target_compile_definitions(cactus PRIVATE TARGET_OS_IPHONE=1) + endif() + + target_link_options(cactus PRIVATE -Wl,-dead_strip -flto) +else() + add_custom_target(cactus ALL + COMMAND libtool -static -o ${CMAKE_BINARY_DIR}/libcactus.a + $ + $ + $ + DEPENDS cactus_engine cactus_graph cactus_kernels + COMMENT "Merging static libraries into libcactus.a" + ) +endif() + +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib) +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) diff --git a/apple/Cactus.swift b/apple/Cactus.swift deleted file mode 100644 index 47c377072..000000000 --- a/apple/Cactus.swift +++ /dev/null @@ -1,916 +0,0 @@ -import Foundation -import cactus - -public final class Cactus: @unchecked Sendable { - - - public struct CompletionResult { - public let text: String - public let functionCalls: [[String: Any]]? - public let promptTokens: Int - public let completionTokens: Int - public let timeToFirstToken: Double - public let totalTime: Double - public let prefillTokensPerSecond: Double - public let decodeTokensPerSecond: Double - public let confidence: Double - public let needsCloudHandoff: Bool - - init(json: [String: Any]) { - self.text = json["response"] as? String ?? "" - self.functionCalls = json["function_calls"] as? [[String: Any]] - self.promptTokens = json["prefill_tokens"] as? Int ?? 0 - self.completionTokens = json["decode_tokens"] as? Int ?? 0 - self.timeToFirstToken = json["time_to_first_token_ms"] as? Double ?? 0 - self.totalTime = json["total_time_ms"] as? Double ?? 0 - self.prefillTokensPerSecond = json["prefill_tps"] as? Double ?? 0 - self.decodeTokensPerSecond = json["decode_tps"] as? Double ?? 0 - self.confidence = json["confidence"] as? Double ?? 1.0 - self.needsCloudHandoff = json["cloud_handoff"] as? Bool ?? false - } - } - - public struct TranscriptionResult { - public let text: String - public let segments: [[String: Any]]? - public let totalTime: Double - - init(json: [String: Any]) { - self.text = json["response"] as? String ?? "" - self.segments = json["segments"] as? [[String: Any]] - self.totalTime = json["total_time_ms"] as? Double ?? 0 - } - } - - public struct VADSegment { - public let start: Int - public let end: Int - - init(dict: [String: Any]) { - self.start = dict["start"] as? Int ?? 0 - self.end = dict["end"] as? Int ?? 0 - } - } - - public struct VADResult { - public let segments: [VADSegment] - public let totalTime: Double - public let ramUsage: Double - - init(json: [String: Any]) { - let segmentsArray = json["segments"] as? [[String: Any]] ?? [] - self.segments = segmentsArray.map { VADSegment(dict: $0) } - self.totalTime = json["total_time_ms"] as? Double ?? 0 - self.ramUsage = json["ram_usage_mb"] as? Double ?? 0 - } - } - - public struct Message { - public let role: String - public let content: String - - public init(role: String, content: String) { - self.role = role - self.content = content - } - - public static func system(_ content: String) -> Message { - Message(role: "system", content: content) - } - - public static func user(_ content: String) -> Message { - Message(role: "user", content: content) - } - - public static func assistant(_ content: String) -> Message { - Message(role: "assistant", content: content) - } - - func toDict() -> [String: String] { - ["role": role, "content": content] - } - } - - public struct CompletionOptions { - public var temperature: Float - public var topP: Float - public var topK: Int - public var maxTokens: Int - public var stopSequences: [String] - public var confidenceThreshold: Float - - public init( - temperature: Float = 0.7, - topP: Float = 0.9, - topK: Int = 40, - maxTokens: Int = 512, - stopSequences: [String] = [], - confidenceThreshold: Float = 0.0 - ) { - self.temperature = temperature - self.topP = topP - self.topK = topK - self.maxTokens = maxTokens - self.stopSequences = stopSequences - self.confidenceThreshold = confidenceThreshold - } - - public static let `default` = CompletionOptions() - - func toJSON() -> String? { - let dict: [String: Any] = [ - "temperature": temperature, - "top_p": topP, - "top_k": topK, - "max_tokens": maxTokens, - "stop": stopSequences, - "confidence_threshold": confidenceThreshold - ] - guard let data = try? JSONSerialization.data(withJSONObject: dict), - let json = String(data: data, encoding: .utf8) else { - return nil - } - return json - } - } - - public struct TranscriptionOptions { - public var language: String? - public var translateToEnglish: Bool - - public init(language: String? = nil, translateToEnglish: Bool = false) { - self.language = language - self.translateToEnglish = translateToEnglish - } - - public static let `default` = TranscriptionOptions() - - func toJSON() -> String? { - var dict: [String: Any] = [ - "translate": translateToEnglish - ] - if let lang = language { - dict["language"] = lang - } - guard let data = try? JSONSerialization.data(withJSONObject: dict), - let json = String(data: data, encoding: .utf8) else { - return nil - } - return json - } - } - - public struct VADOptions { - public var threshold: Float? - public var negThreshold: Float? - public var minSpeechDurationMs: Int? - public var maxSpeechDurationS: Float? - public var minSilenceDurationMs: Int? - public var speechPadMs: Int? - public var windowSizeSamples: Int? - public var samplingRate: Int? - - public init( - threshold: Float? = nil, - negThreshold: Float? = nil, - minSpeechDurationMs: Int? = nil, - maxSpeechDurationS: Float? = nil, - minSilenceDurationMs: Int? = nil, - speechPadMs: Int? = nil, - windowSizeSamples: Int? = nil, - samplingRate: Int? = nil - ) { - self.threshold = threshold - self.negThreshold = negThreshold - self.minSpeechDurationMs = minSpeechDurationMs - self.maxSpeechDurationS = maxSpeechDurationS - self.minSilenceDurationMs = minSilenceDurationMs - self.speechPadMs = speechPadMs - self.windowSizeSamples = windowSizeSamples - self.samplingRate = samplingRate - } - - public static let `default` = VADOptions() - - func toJSON() -> String? { - var dict: [String: Any] = [:] - if let threshold = threshold { dict["threshold"] = threshold } - if let negThreshold = negThreshold { dict["neg_threshold"] = negThreshold } - if let minSpeechDurationMs = minSpeechDurationMs { dict["min_speech_duration_ms"] = minSpeechDurationMs } - if let maxSpeechDurationS = maxSpeechDurationS { dict["max_speech_duration_s"] = maxSpeechDurationS } - if let minSilenceDurationMs = minSilenceDurationMs { dict["min_silence_duration_ms"] = minSilenceDurationMs } - if let speechPadMs = speechPadMs { dict["speech_pad_ms"] = speechPadMs } - if let windowSizeSamples = windowSizeSamples { dict["window_size_samples"] = windowSizeSamples } - if let samplingRate = samplingRate { dict["sampling_rate"] = samplingRate } - - guard !dict.isEmpty else { return nil } - guard let data = try? JSONSerialization.data(withJSONObject: dict), - let json = String(data: data, encoding: .utf8) else { - return nil - } - return json - } - } - - public enum CactusError: Error, LocalizedError { - case initializationFailed(String) - case completionFailed(String) - case transcriptionFailed(String) - case vadFailed(String) - case embeddingFailed(String) - case invalidResponse - - public var errorDescription: String? { - switch self { - case .initializationFailed(let msg): return "Initialization failed: \(msg)" - case .completionFailed(let msg): return "Completion failed: \(msg)" - case .transcriptionFailed(let msg): return "Transcription failed: \(msg)" - case .vadFailed(let msg): return "VAD failed: \(msg)" - case .embeddingFailed(let msg): return "Embedding failed: \(msg)" - case .invalidResponse: return "Invalid response from model" - } - } - } - - - private let handle: UnsafeMutableRawPointer - private static let defaultBufferSize = 65536 - private static let _frameworkInitialized: Void = { - cactus_set_telemetry_environment("swift", nil, nil) - if let bundleId = Bundle.main.bundleIdentifier { - bundleId.withCString { cactus_set_app_id($0) } - } - }() - - public init(modelPath: String, corpusDir: String? = nil, cacheIndex: Bool = false) throws { - _ = Self._frameworkInitialized - guard let h = cactus_init(modelPath, corpusDir, cacheIndex) else { - let error = String(cString: cactus_get_last_error()) - throw CactusError.initializationFailed(error.isEmpty ? "Unknown error" : error) - } - self.handle = h - } - - deinit { - cactus_destroy(handle) - } - - public static func setTelemetryEnvironment(_ path: String) { - cactus_set_telemetry_environment(nil, path, nil) - } - - public func complete( - messages: [Message], - options: CompletionOptions = .default, - tools: [[String: Any]]? = nil, - onToken: ((String, UInt32) -> Void)? = nil - ) throws -> CompletionResult { - let messagesJSON = try serializeMessages(messages) - let optionsJSON = options.toJSON() - let toolsJSON = try serializeTools(tools) - - var buffer = [CChar](repeating: 0, count: Self.defaultBufferSize) - - let callbackContext = onToken.map { TokenCallbackContext(callback: $0) } - let contextPtr = callbackContext.map { Unmanaged.passUnretained($0).toOpaque() } - - let result = buffer.withUnsafeMutableBufferPointer { bufferPtr in - cactus_complete( - handle, - messagesJSON, - bufferPtr.baseAddress, - bufferPtr.count, - optionsJSON, - toolsJSON, - onToken != nil ? tokenCallbackBridge : nil, - contextPtr, - nil, - 0 - ) - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw CactusError.completionFailed(error.isEmpty ? "Unknown error" : error) - } - - let responseString = String(cString: buffer) - guard let json = parseJSON(responseString) else { - throw CactusError.invalidResponse - } - - if let errorMsg = json["error"] as? String { - throw CactusError.completionFailed(errorMsg) - } - - return CompletionResult(json: json) - } - - public func complete( - _ prompt: String, - options: CompletionOptions = .default - ) throws -> CompletionResult { - try complete(messages: [.user(prompt)], options: options) - } - - public func transcribe( - audioPath: String, - prompt: String? = nil, - options: TranscriptionOptions = .default - ) throws -> TranscriptionResult { - var buffer = [CChar](repeating: 0, count: Self.defaultBufferSize) - let optionsJSON = options.toJSON() - - let result = buffer.withUnsafeMutableBufferPointer { bufferPtr in - cactus_transcribe( - handle, - audioPath, - prompt, - bufferPtr.baseAddress, - bufferPtr.count, - optionsJSON, - nil, - nil, - nil, - 0 - ) - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw CactusError.transcriptionFailed(error.isEmpty ? "Unknown error" : error) - } - - let responseString = String(cString: buffer) - guard let json = parseJSON(responseString) else { - throw CactusError.invalidResponse - } - - return TranscriptionResult(json: json) - } - - public func transcribe( - pcmData: Data, - prompt: String? = nil, - options: TranscriptionOptions = .default - ) throws -> TranscriptionResult { - var buffer = [CChar](repeating: 0, count: Self.defaultBufferSize) - let optionsJSON = options.toJSON() - - let result = pcmData.withUnsafeBytes { pcmPtr in - buffer.withUnsafeMutableBufferPointer { bufferPtr in - cactus_transcribe( - handle, - nil, - prompt, - bufferPtr.baseAddress, - bufferPtr.count, - optionsJSON, - nil, - nil, - pcmPtr.baseAddress?.assumingMemoryBound(to: UInt8.self), - pcmData.count - ) - } - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw CactusError.transcriptionFailed(error.isEmpty ? "Unknown error" : error) - } - - let responseString = String(cString: buffer) - guard let json = parseJSON(responseString) else { - throw CactusError.invalidResponse - } - - return TranscriptionResult(json: json) - } - - public func embed(text: String, normalize: Bool = true) throws -> [Float] { - var embeddingBuffer = [Float](repeating: 0, count: 4096) - var embeddingDim: Int = 0 - - let result = embeddingBuffer.withUnsafeMutableBufferPointer { bufferPtr in - cactus_embed( - handle, - text, - bufferPtr.baseAddress, - bufferPtr.count, - &embeddingDim, - normalize - ) - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw CactusError.embeddingFailed(error.isEmpty ? "Unknown error" : error) - } - - return Array(embeddingBuffer.prefix(embeddingDim)) - } - - public func ragQuery(_ query: String, topK: Int = 5) throws -> String { - var buffer = [CChar](repeating: 0, count: Self.defaultBufferSize) - - let result = buffer.withUnsafeMutableBufferPointer { bufferPtr in - cactus_rag_query( - handle, - query, - bufferPtr.baseAddress, - bufferPtr.count, - topK - ) - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw CactusError.completionFailed(error.isEmpty ? "Unknown error" : error) - } - - return String(cString: buffer) - } - - public func tokenize(_ text: String) throws -> [UInt32] { - var tokenBuffer = [UInt32](repeating: 0, count: 8192) - var tokenLen: Int = 0 - - let result = tokenBuffer.withUnsafeMutableBufferPointer { bufferPtr in - cactus_tokenize( - handle, - text, - bufferPtr.baseAddress, - bufferPtr.count, - &tokenLen - ) - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw CactusError.completionFailed(error.isEmpty ? "Unknown error" : error) - } - - return Array(tokenBuffer.prefix(tokenLen)) - } - - public func scoreWindow(tokens: [UInt32], start: Int, end: Int, context: Int) throws -> String { - var buffer = [CChar](repeating: 0, count: Self.defaultBufferSize) - - let result = tokens.withUnsafeBufferPointer { tokenPtr in - buffer.withUnsafeMutableBufferPointer { bufferPtr in - cactus_score_window( - handle, - tokenPtr.baseAddress, - tokenPtr.count, - start, - end, - context, - bufferPtr.baseAddress, - bufferPtr.count - ) - } - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw CactusError.completionFailed(error.isEmpty ? "Unknown error" : error) - } - - return String(cString: buffer) - } - - public func imageEmbed(_ imagePath: String) throws -> [Float] { - var embeddingBuffer = [Float](repeating: 0, count: 4096) - var embeddingDim: Int = 0 - - let result = embeddingBuffer.withUnsafeMutableBufferPointer { bufferPtr in - cactus_image_embed( - handle, - imagePath, - bufferPtr.baseAddress, - bufferPtr.count, - &embeddingDim - ) - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw CactusError.embeddingFailed(error.isEmpty ? "Unknown error" : error) - } - - return Array(embeddingBuffer.prefix(embeddingDim)) - } - - public func audioEmbed(_ audioPath: String) throws -> [Float] { - var embeddingBuffer = [Float](repeating: 0, count: 4096) - var embeddingDim: Int = 0 - - let result = embeddingBuffer.withUnsafeMutableBufferPointer { bufferPtr in - cactus_audio_embed( - handle, - audioPath, - bufferPtr.baseAddress, - bufferPtr.count, - &embeddingDim - ) - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw CactusError.embeddingFailed(error.isEmpty ? "Unknown error" : error) - } - - return Array(embeddingBuffer.prefix(embeddingDim)) - } - - public func vad( - audioPath: String, - options: VADOptions = .default - ) throws -> VADResult { - _ = (audioPath, options) - throw CactusError.vadFailed("VAD not implemented") - } - - public func vad( - pcmData: Data, - options: VADOptions = .default - ) throws -> VADResult { - _ = (pcmData, options) - throw CactusError.vadFailed("VAD not implemented") - } - - public func createStreamTranscriber(options: TranscriptionOptions = .default) throws -> StreamTranscriber { - _ = options - throw CactusError.transcriptionFailed("stream transcribe not implemented") - } - - public func reset() { - cactus_reset(handle) - } - - public func stop() { - cactus_stop(handle) - } - - - private func serializeMessages(_ messages: [Message]) throws -> String { - let dicts = messages.map { $0.toDict() } - guard let data = try? JSONSerialization.data(withJSONObject: dicts), - let json = String(data: data, encoding: .utf8) else { - throw CactusError.completionFailed("Failed to serialize messages") - } - return json - } - - private func serializeTools(_ tools: [[String: Any]]?) throws -> String? { - guard let tools = tools else { return nil } - guard let data = try? JSONSerialization.data(withJSONObject: tools), - let json = String(data: data, encoding: .utf8) else { - throw CactusError.completionFailed("Failed to serialize tools") - } - return json - } - - private func parseJSON(_ string: String) -> [String: Any]? { - guard let data = string.data(using: .utf8), - let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { - return nil - } - return json - } -} - - -private class TokenCallbackContext { - let callback: (String, UInt32) -> Void - init(callback: @escaping (String, UInt32) -> Void) { - self.callback = callback - } -} - -private func tokenCallbackBridge(token: UnsafePointer?, tokenId: UInt32, userData: UnsafeMutableRawPointer?) { - guard let token = token, let userData = userData else { return } - let context = Unmanaged.fromOpaque(userData).takeUnretainedValue() - let tokenString = String(cString: token) - context.callback(tokenString, tokenId) -} - - -#if os(iOS) || os(macOS) || os(tvOS) || os(watchOS) || os(visionOS) -@available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0, *) -#endif -public extension Cactus { - - func complete( - messages: [Message], - options: CompletionOptions = .default, - tools: [[String: Any]]? = nil - ) async throws -> CompletionResult { - try await withCheckedThrowingContinuation { continuation in - DispatchQueue.global(qos: .userInitiated).async { - do { - let result = try self.complete(messages: messages, options: options, tools: tools) - continuation.resume(returning: result) - } catch { - continuation.resume(throwing: error) - } - } - } - } - - func completeStream( - messages: [Message], - options: CompletionOptions = .default - ) -> AsyncThrowingStream { - AsyncThrowingStream { continuation in - DispatchQueue.global(qos: .userInitiated).async { - do { - _ = try self.complete(messages: messages, options: options) { token, _ in - continuation.yield(token) - } - continuation.finish() - } catch { - continuation.finish(throwing: error) - } - } - } - } - - func transcribe( - audioPath: String, - prompt: String? = nil, - options: TranscriptionOptions = .default - ) async throws -> TranscriptionResult { - try await withCheckedThrowingContinuation { continuation in - DispatchQueue.global(qos: .userInitiated).async { - do { - let result = try self.transcribe(audioPath: audioPath, prompt: prompt, options: options) - continuation.resume(returning: result) - } catch { - continuation.resume(throwing: error) - } - } - } - } - - func embed(text: String, normalize: Bool = true) async throws -> [Float] { - try await withCheckedThrowingContinuation { continuation in - DispatchQueue.global(qos: .userInitiated).async { - do { - let result = try self.embed(text: text, normalize: normalize) - continuation.resume(returning: result) - } catch { - continuation.resume(throwing: error) - } - } - } - } - - func vad( - audioPath: String, - options: VADOptions = .default - ) async throws -> VADResult { - try await withCheckedThrowingContinuation { continuation in - DispatchQueue.global(qos: .userInitiated).async { - do { - let result = try self.vad(audioPath: audioPath, options: options) - continuation.resume(returning: result) - } catch { - continuation.resume(throwing: error) - } - } - } - } - - func vad( - pcmData: Data, - options: VADOptions = .default - ) async throws -> VADResult { - try await withCheckedThrowingContinuation { continuation in - DispatchQueue.global(qos: .userInitiated).async { - do { - let result = try self.vad(pcmData: pcmData, options: options) - continuation.resume(returning: result) - } catch { - continuation.resume(throwing: error) - } - } - } - } -} - - -public final class StreamTranscriber: @unchecked Sendable { - - private var handle: UnsafeMutableRawPointer? - private static let defaultBufferSize = 65536 - - init(handle: UnsafeMutableRawPointer) { - self.handle = handle - } - - deinit { - close() - } - - public func process(pcmData: Data) throws -> Cactus.TranscriptionResult { - _ = pcmData - throw Cactus.CactusError.transcriptionFailed("stream transcribe not implemented") - } - - public func stop() throws -> Cactus.TranscriptionResult { - self.handle = nil - throw Cactus.CactusError.transcriptionFailed("stream transcribe not implemented") - } - - public func close() { - self.handle = nil - } -} - - -public final class CactusIndex: @unchecked Sendable { - - public struct IndexResult { - public let id: Int - public let score: Float - } - - public enum IndexError: Error, LocalizedError { - case initializationFailed(String) - case operationFailed(String) - - public var errorDescription: String? { - switch self { - case .initializationFailed(let msg): return "Index initialization failed: \(msg)" - case .operationFailed(let msg): return "Index operation failed: \(msg)" - } - } - } - - private var handle: UnsafeMutableRawPointer? - - public init(indexDir: String, embeddingDim: Int) throws { - guard let h = cactus_index_init(indexDir, embeddingDim) else { - throw IndexError.initializationFailed("Failed to initialize index") - } - self.handle = h - } - - deinit { - close() - } - - public func add( - ids: [Int], - documents: [String], - embeddings: [[Float]], - metadatas: [String]? = nil - ) throws { - guard let handle = handle else { - throw IndexError.operationFailed("Index has been closed") - } - - let count = ids.count - let embeddingDim = embeddings[0].count - - var idArray = ids.map { Int32($0) } - var docPtrs = documents.map { strdup($0) } - var metaPtrs: [UnsafeMutablePointer?]? = metadatas?.map { strdup($0) } - var embPtrs = embeddings.map { emb -> UnsafePointer? in - let ptr = UnsafeMutablePointer.allocate(capacity: emb.count) - ptr.initialize(from: emb, count: emb.count) - return UnsafePointer(ptr) - } - - let result = idArray.withUnsafeMutableBufferPointer { idPtr in - docPtrs.withUnsafeMutableBufferPointer { docPtr in - embPtrs.withUnsafeMutableBufferPointer { embPtr in - if let metaPtrs = metaPtrs { - var metaPtrsCopy = metaPtrs - return metaPtrsCopy.withUnsafeMutableBufferPointer { metaPtr in - cactus_index_add( - handle, - idPtr.baseAddress, - unsafeBitCast(docPtr.baseAddress, to: UnsafeMutablePointer?>?.self), - unsafeBitCast(metaPtr.baseAddress, to: UnsafeMutablePointer?>?.self), - embPtr.baseAddress, - count, - embeddingDim - ) - } - } else { - return cactus_index_add( - handle, - idPtr.baseAddress, - unsafeBitCast(docPtr.baseAddress, to: UnsafeMutablePointer?>?.self), - nil, - embPtr.baseAddress, - count, - embeddingDim - ) - } - } - } - } - - docPtrs.forEach { free($0) } - metaPtrs?.forEach { free($0) } - embPtrs.forEach { ptr in - if let ptr = ptr { - UnsafeMutablePointer(mutating: ptr).deallocate() - } - } - - if result < 0 { - throw IndexError.operationFailed("Failed to add documents to index") - } - } - - public func delete(ids: [Int]) throws { - guard let handle = handle else { - throw IndexError.operationFailed("Index has been closed") - } - - var idArray = ids.map { Int32($0) } - - let result = idArray.withUnsafeMutableBufferPointer { idPtr in - cactus_index_delete(handle, idPtr.baseAddress, ids.count) - } - - if result < 0 { - throw IndexError.operationFailed("Failed to delete documents from index") - } - } - - public func query(embedding: [Float], topK: Int = 5) throws -> [IndexResult] { - guard let handle = handle else { - throw IndexError.operationFailed("Index has been closed") - } - - var embeddingCopy = embedding - var idBuffer = [Int32](repeating: 0, count: topK) - var scoreBuffer = [Float](repeating: 0, count: topK) - var idBufferSize = topK - var scoreBufferSize = topK - - let result = embeddingCopy.withUnsafeMutableBufferPointer { embPtr in - idBuffer.withUnsafeMutableBufferPointer { idPtr in - scoreBuffer.withUnsafeMutableBufferPointer { scorePtr in - var embPtrPtr: UnsafePointer? = embPtr.baseAddress.map { UnsafePointer($0) } - var idPtrPtr: UnsafeMutablePointer? = idPtr.baseAddress - var scorePtrPtr: UnsafeMutablePointer? = scorePtr.baseAddress - - return withUnsafeMutablePointer(to: &embPtrPtr) { embPtrPtrPtr in - withUnsafeMutablePointer(to: &idPtrPtr) { idPtrPtrPtr in - withUnsafeMutablePointer(to: &scorePtrPtr) { scorePtrPtrPtr in - withUnsafeMutablePointer(to: &idBufferSize) { idSizePtr in - withUnsafeMutablePointer(to: &scoreBufferSize) { scoreSizePtr in - cactus_index_query( - handle, - embPtrPtrPtr, - 1, - embedding.count, - nil, - idPtrPtrPtr, - idSizePtr, - scorePtrPtrPtr, - scoreSizePtr - ) - } - } - } - } - } - } - } - } - - if result < 0 { - let error = String(cString: cactus_get_last_error()) - throw IndexError.operationFailed(error.isEmpty ? "Unknown error" : error) - } - - return (0..CFBundleVersion 1.0.0 MinimumOSVersion - 12.0 + 13.0 diff --git a/apple/README.md b/apple/README.md index a17942e24..e2a5cc710 100644 --- a/apple/README.md +++ b/apple/README.md @@ -1,468 +1,36 @@ ---- -title: "Cactus Swift Multiplatform SDK" -description: "Swift API for running AI models on-device on iOS, macOS, and Android. Supports transcription, embeddings, RAG, and tool calling." -keywords: ["Swift SDK", "iOS", "macOS", "XCFramework", "on-device AI", "Apple Silicon", "NPU"] ---- +# Apple Build -# Cactus for Swift Multiplatform +Builds `libcactus` for iOS and macOS. -Run AI models on-device with a simple Swift API on iOS, macOS, and Android. - -> **Model weights:** Pre-converted weights for all supported models at [huggingface.co/Cactus-Compute](https://huggingface.co/Cactus-Compute). - -## Building +## Usage - ```bash -git clone https://github.com/cactus-compute/cactus && cd cactus && source ./setup cactus build --apple ``` -Build outputs (in `apple/`): - -| File | Description | -|------|-------------| -| `cactus-ios.xcframework/` | iOS framework (device + simulator) | -| `cactus-macos.xcframework/` | macOS framework | -| `libcactus-device.a` | Static library for iOS device | -| `libcactus-simulator.a` | Static library for iOS simulator | - - -See the main [README.md](../README.md) for how to use CLI & download weights - -For Android, build `libcactus.so` from the `android/` directory. - -### Vendored libcurl (iOS + macOS) - -To bundle libcurl from this repo instead of relying on system curl, place artifacts under: - -- `libs/curl/include/curl/*.h` -- `libs/curl/ios/device/libcurl.a` -- `libs/curl/ios/simulator/libcurl.a` -- `libs/curl/macos/libcurl.a` - -Build scripts auto-detect `libs/curl`. Override with: +Or directly: ```bash -CACTUS_CURL_ROOT=/absolute/path/to/curl cactus build --apple -``` - -## Integration - - -### iOS/macOS: XCFramework (Recommended) - -1. Drag `cactus-ios.xcframework` (or `cactus-macos.xcframework`) into your Xcode project -2. Ensure "Embed & Sign" is selected in "Frameworks, Libraries, and Embedded Content" -3. Copy `Cactus.swift` into your project - -### iOS/macOS: Static Library - -1. Add `libcactus-device.a` (or `libcactus-simulator.a`) to "Link Binary With Libraries" -2. Create a folder with `cactus_ffi.h` and `module.modulemap`, add to Build Settings: - - "Header Search Paths" → path to folder - - "Import Paths" (Swift) → path to folder -3. Copy `Cactus.swift` into your project - - -### Android (Swift SDK) - -Requires [Swift SDK for Android](https://www.swift.org/documentation/articles/swift-sdk-for-android-getting-started.html). - -1. Copy files to your Swift project: - - `libcactus.so` → your library path - - `cactus_ffi.h` → your include path - - `module.android.modulemap` → rename to `module.modulemap` in include path - - `Cactus.swift` → your sources - -2. Build with Swift SDK for Android: -```bash -swift build --swift-sdk aarch64-unknown-linux-android28 \ - -Xswiftc -I/path/to/include \ - -Xlinker -L/path/to/lib \ - -Xlinker -lcactus -``` - -3. Bundle `libcactus.so` with your APK in `jniLibs/arm64-v8a/` - -## Usage - -Handles are typed as `CactusModelT`, `CactusIndexT`, and `CactusStreamTranscribeT` (all `UnsafeMutableRawPointer` aliases). - -### Basic Completion - - -```swift -import Foundation - -let model = try cactusInit("/path/to/model", nil, false) -defer { cactusDestroy(model) } - -let messages = #"[{"role":"user","content":"What is the capital of France?"}]"# -let resultJson = try cactusComplete(model, messages, nil, nil, nil) -print(resultJson) -``` - - -For vision models (LFM2-VL, LFM2.5-VL, Gemma4, Qwen3.5), add `"images": ["path/to/image.png"]` to any message. For audio models (Gemma4), add `"audio": ["path/to/audio.wav"]`. See [Engine API](/docs/cactus_engine.md) for details. - -### Completion with Options and Streaming - -```swift -let options = #"{"max_tokens":256,"temperature":0.7}"# - -let resultJson = try cactusComplete(model, messages, options, nil as String?) { token, _ in - print(token, terminator: "") -} -print(resultJson) -``` - -### Prefill - -Pre-processes input text and populates the KV cache without generating output tokens. This reduces latency for subsequent calls to `cactusComplete`. - -```swift -func cactusPrefill( - _ model: CactusModelT, - _ messagesJson: String, - _ optionsJson: String?, - _ toolsJson: String? -) throws -> String -``` - -```swift -let tools = #"[ - { - "type": "function", - "function": { - "name": "get_weather", - "description": "Get weather for a location", - "parameters": { - "type": "object", - "properties": { - "location": {"type": "string", "description": "City, State, Country"} - }, - "required": ["location"] - } - } - } -]"# - -let messages = #"[ - {"role": "system", "content": "You are a helpful assistant."}, - {"role": "user", "content": "What is the weather in Paris?"}, - {"role": "assistant", "content": "<|tool_call_start|>get_weather(location=\"Paris\")<|tool_call_end|>"}, - {"role": "tool", "content": "{\"name\": \"get_weather\", \"content\": \"Sunny, 72°F\"}"}, - {"role": "assistant", "content": "It's sunny and 72°F in Paris!"} -]"# - -let resultJson = try cactusPrefill(model, messages, nil, tools) - -let completionMessages = #"[ - {"role": "system", "content": "You are a helpful assistant."}, - {"role": "user", "content": "What is the weather in Paris?"}, - {"role": "assistant", "content": "<|tool_call_start|>get_weather(location=\"Paris\")<|tool_call_end|>"}, - {"role": "tool", "content": "{\"name\": \"get_weather\", \"content\": \"Sunny, 72°F\"}"}, - {"role": "assistant", "content": "It's sunny and 72°F in Paris!"}, - {"role": "user", "content": "What about SF?"} -]"# -let completion = try cactusComplete(model, completionMessages, nil, tools, nil) -``` - -**Response format:** -```json -{ - "success": true, - "error": null, - "prefill_tokens": 25, - "prefill_tps": 166.1, - "total_time_ms": 150.5, - "ram_usage_mb": 245.67 -} -``` - -### Audio Transcription - -```swift -// From file -let resultJson = try cactusTranscribe(model, "/path/to/audio.wav", nil, nil, nil as ((String, UInt32) -> Void)?, nil as Data?) -print(resultJson) - -// From PCM data (16 kHz mono) -let pcmData: Data = ... -let resultJson2 = try cactusTranscribe(model, nil, nil, nil, nil as ((String, UInt32) -> Void)?, pcmData) -print(resultJson2) -``` - -`segments` contains timestamps (seconds): phrase-level for Whisper, word-level for Parakeet TDT, one segment per transcription window for Parakeet CTC and Moonshine (consecutive VAD speech regions up to 30s). - -```swift -if let data = resultJson.data(using: .utf8), - let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any], - let segments = obj["segments"] as? [[String: Any]] { - for seg in segments { - let start = seg["start"] as? Double ?? 0 - let end = seg["end"] as? Double ?? 0 - let text = seg["text"] as? String ?? "" - print(String(format: "[%.3fs - %.3fs] %@", start, end, text)) - } -} -``` - -**Custom vocabulary** biases the decoder toward domain-specific words (supported for Whisper and Moonshine models). Pass `custom_vocabulary` and `vocabulary_boost` in the options JSON: - -```swift -let options = #"{"custom_vocabulary": ["Omeprazole", "HIPAA", "Cactus"], "vocabulary_boost": 3.0}"# -let result = try cactusTranscribe(model, "/path/to/audio.wav", nil, options, nil as ((String, UInt32) -> Void)?, nil as Data?) -``` - -### Streaming Transcription - -```swift -let stream = try cactusStreamTranscribeStart(model, nil as String?) - -let partialJson = try cactusStreamTranscribeProcess(stream, audioChunk) -print(partialJson) - -let finalJson = try cactusStreamTranscribeStop(stream) -print(finalJson) -``` - -Streaming also accepts `custom_vocabulary` in the options passed to `cactusStreamTranscribeStart`. The bias is applied for the lifetime of the stream session. - -### Embeddings - -```swift -let embedding = try cactusEmbed(model, "Hello, world!", true) -let imageEmbedding = try cactusImageEmbed(model, "/path/to/image.jpg") -let audioEmbedding = try cactusAudioEmbed(model, "/path/to/audio.wav") -``` - -### Tokenization - -```swift -let tokens = try cactusTokenize(model, "Hello, world!") -let scoresJson = try cactusScoreWindow(model, tokens, 0, tokens.count, min(tokens.count, 512)) -print(scoresJson) -``` - -### Detect Language - -```swift -let langJson = try cactusDetectLanguage(model, "/path/to/audio.wav", nil, nil) -print(langJson) -``` - -### VAD - -```swift -let vadJson = try cactusVad(model, "/path/to/audio.wav", nil as String?, nil as Data?) -print(vadJson) -``` - -### Diarize - -```swift -let diarizeJson = try cactusDiarize(model, "/path/to/audio.wav", nil, nil as Data?) -print(diarizeJson) -``` - -Options (all optional): -- `step_ms` (int, default 1000) — sliding window stride in milliseconds -- `threshold` (float) — zero out per-speaker scores below this value -- `num_speakers` (int) — keep only the N most active speakers -- `min_speakers` / `max_speakers` (int) — speaker count bounds -- `raw_powerset` (bool, default false) — return raw 7-class powerset scores instead of 3-speaker probabilities - -### Embed Speaker - -```swift -let embedJson = try cactusEmbedSpeaker(model, "/path/to/audio.wav", nil, nil as Data?) -print(embedJson) - -// With diarization mask for speaker-specific embedding -let embedJson = try cactusEmbedSpeaker(model, "/path/to/audio.wav", nil, nil as Data?, maskWeights) -``` - -Returns a 256-dimensional speaker embedding. When `maskWeights` (a per-frame weight array from diarization) is provided, the embedding is extracted using weighted stats pooling for speaker-specific embeddings. - -### RAG - -```swift -let ragJson = try cactusRagQuery(model, "What is machine learning?", 5) -print(ragJson) -``` - -### Vector Index - -```swift -let index = try cactusIndexInit("/path/to/index", 384) -defer { cactusIndexDestroy(index) } - -try cactusIndexAdd(index, [Int32(1), Int32(2)], ["doc1", "doc2"], - [[Float(0.1), Float(0.2), ...], [Float(0.3), Float(0.4), ...]], nil) - -let results = try cactusIndexQuery(index, [Float(0.1), Float(0.2), ...], nil) - -try cactusIndexDelete(index, [Int32(2)]) -try cactusIndexCompact(index) -``` - -## API Reference - -All functions are top-level and mirror the C FFI directly. - -### Types - -```swift -public typealias CactusModelT = UnsafeMutableRawPointer -public typealias CactusIndexT = UnsafeMutableRawPointer -public typealias CactusStreamTranscribeT = UnsafeMutableRawPointer -``` - -All `throws` functions throw `NSError` (domain `"cactus"`) on failure. - -### Init / Lifecycle - -```swift -func cactusInit(_ modelPath: String, _ corpusDir: String?, _ cacheIndex: Bool) throws -> CactusModelT -func cactusDestroy(_ model: CactusModelT) -func cactusReset(_ model: CactusModelT) -func cactusStop(_ model: CactusModelT) -func cactusGetLastError() -> String -``` - -### Prefill - -```swift -func cactusPrefill( - _ model: CactusModelT, - _ messagesJson: String, - _ optionsJson: String?, - _ toolsJson: String?, - _ pcmData: Data? = nil -) throws -> String -``` - -### Completion - -```swift -func cactusComplete( - _ model: CactusModelT, - _ messagesJson: String, - _ optionsJson: String?, - _ toolsJson: String?, - _ callback: ((String, UInt32) -> Void)?, - _ pcmData: Data? = nil -) throws -> String -``` - -### Transcription - -```swift -func cactusTranscribe( - _ model: CactusModelT, - _ audioPath: String?, - _ prompt: String?, - _ optionsJson: String?, - _ callback: ((String, UInt32) -> Void)?, - _ pcmData: Data? -) throws -> String - -func cactusStreamTranscribeStart(_ model: CactusModelT, _ optionsJson: String?) throws -> CactusStreamTranscribeT -func cactusStreamTranscribeProcess(_ stream: CactusStreamTranscribeT, _ pcmData: Data) throws -> String -func cactusStreamTranscribeStop(_ stream: CactusStreamTranscribeT) throws -> String -``` - -### Embeddings - -```swift -func cactusEmbed(_ model: CactusModelT, _ text: String, _ normalize: Bool) throws -> [Float] -func cactusImageEmbed(_ model: CactusModelT, _ imagePath: String) throws -> [Float] -func cactusAudioEmbed(_ model: CactusModelT, _ audioPath: String) throws -> [Float] +bash apple/build.sh ``` -### Tokenization / Scoring +## Output -```swift -func cactusTokenize(_ model: CactusModelT, _ text: String) throws -> [UInt32] -func cactusScoreWindow(_ model: CactusModelT, _ tokens: [UInt32], _ start: Int, _ end: Int, _ context: Int) throws -> String -``` - -### Detect Language - -```swift -func cactusDetectLanguage(_ model: CactusModelT, _ audioPath: String?, _ optionsJson: String?, _ pcmData: Data?) throws -> String -``` - -### VAD +- `libcactus-device.a` — iOS device (arm64) +- `libcactus-simulator.a` — iOS simulator (arm64) +- `cactus-ios.xcframework/` — iOS XCFramework (device + simulator) +- `cactus-macos.xcframework/` — macOS XCFramework (arm64) -```swift -func cactusVad(_ model: CactusModelT, _ audioPath: String?, _ optionsJson: String?, _ pcmData: Data?) throws -> String -``` - -### Diarize - -```swift -func cactusDiarize(_ model: CactusModelT, _ audioPath: String?, _ optionsJson: String?, _ pcmData: Data?) throws -> String -``` +## Options -### Embed Speaker - -```swift -func cactusEmbedSpeaker(_ model: CactusModelT, _ audioPath: String?, _ optionsJson: String?, _ pcmData: Data?, _ maskWeights: [Float]? = nil) throws -> String -``` - -### RAG - -```swift -func cactusRagQuery(_ model: CactusModelT, _ query: String, _ topK: Int) throws -> String -``` - -### Vector Index - -```swift -func cactusIndexInit(_ indexDir: String, _ embeddingDim: Int) throws -> CactusIndexT -func cactusIndexDestroy(_ index: CactusIndexT) -func cactusIndexAdd(_ index: CactusIndexT, _ ids: [Int32], _ documents: [String], _ embeddings: [[Float]], _ metadatas: [String]?) throws -func cactusIndexDelete(_ index: CactusIndexT, _ ids: [Int32]) throws -func cactusIndexGet(_ index: CactusIndexT, _ ids: [Int32]) throws -> String -func cactusIndexQuery(_ index: CactusIndexT, _ embedding: [Float], _ optionsJson: String?) throws -> String -func cactusIndexCompact(_ index: CactusIndexT) throws -``` - -### Logging - -```swift -func cactusLogSetLevel(_ level: Int32) // 0=DEBUG, 1=INFO, 2=WARN (default), 3=ERROR, 4=NONE -func cactusLogSetCallback(_ callback: ((Int32, String, String) -> Void)?) -``` - -### Telemetry - -```swift -func cactusSetTelemetryEnvironment(_ path: String) -func cactusSetAppId(_ appId: String) -func cactusTelemetryFlush() -func cactusTelemetryShutdown() -``` +| Variable | Default | Description | +|----------|---------|-------------| +| `BUILD_STATIC` | `true` | Build static libraries | +| `BUILD_XCFRAMEWORK` | `true` | Build XCFrameworks | +| `CMAKE_BUILD_TYPE` | `Release` | CMake build type | +| `CACTUS_CURL_ROOT` | `cactus-engine/libs/curl` | Vendored libcurl path | ## Requirements -**Apple Platforms:** -- iOS 13.0+ / macOS 13.0+ -- Xcode 14.0+ -- Swift 5.7+ - -**Android:** -- Swift 6.0+ with [Swift SDK for Android](https://www.swift.org/documentation/articles/swift-sdk-for-android-getting-started.html) -- Android NDK 27d+ -- Android API 28+ / arm64-v8a - -## See Also - -- [Cactus Engine API](/docs/cactus_engine.md) — Full C API reference underlying the Swift bindings -- [Cactus Index API](/docs/cactus_index.md) — Vector database API for RAG applications -- [Fine-tuning Guide](/docs/finetuning.md) — Deploy custom fine-tunes to iOS/macOS -- [Kotlin/Android SDK](/android/) — Kotlin alternative for Android -- [Flutter SDK](/flutter/) — Cross-platform alternative using Dart +- Xcode with iOS SDK +- CMake 3.10+ diff --git a/apple/build.sh b/apple/build.sh index cd616eaea..8fad949c2 100755 --- a/apple/build.sh +++ b/apple/build.sh @@ -32,10 +32,8 @@ echo "Vendored libcurl root: $CACTUS_CURL_ROOT" function cp_headers() { mkdir -p "$ROOT_DIR/apple/$1/$2/cactus.framework/Headers" cp "$ROOT_DIR/cactus-engine/cactus_engine.h" "$ROOT_DIR/apple/$1/$2/cactus.framework/Headers/" 2>/dev/null || true - cp "$ROOT_DIR/cactus-engine/src/engine.h" "$ROOT_DIR/apple/$1/$2/cactus.framework/Headers/" 2>/dev/null || true cp "$ROOT_DIR/cactus-graph/cactus_graph.h" "$ROOT_DIR/apple/$1/$2/cactus.framework/Headers/" 2>/dev/null || true cp "$ROOT_DIR/cactus-kernels/cactus_kernels.h" "$ROOT_DIR/apple/$1/$2/cactus.framework/Headers/" 2>/dev/null || true - cp "$ROOT_DIR/cactus/"*.h "$ROOT_DIR/apple/$1/$2/cactus.framework/Headers/" 2>/dev/null || true } function create_ios_xcframework_info_plist() { diff --git a/apple/module.modulemap b/apple/module.modulemap deleted file mode 100644 index daa014138..000000000 --- a/apple/module.modulemap +++ /dev/null @@ -1,5 +0,0 @@ -framework module cactus { - umbrella header "cactus_ffi.h" - export * - module * { export * } -} diff --git a/bindings/README.md b/bindings/README.md new file mode 100644 index 000000000..c43d5a420 --- /dev/null +++ b/bindings/README.md @@ -0,0 +1,19 @@ +# Bindings + +Language-facing interop layers live here. + +These are bindings, not SDKs: + +- `python/` uses `ctypes` +- `swift/` uses a C module map +- `kotlin/` uses JNI +- `flutter/` uses Dart FFI +- `rust/` uses raw `extern "C"` declarations +- `react-native/` contains a thin React Native bridge backed by the raw Kotlin and Swift bindings + +Platform-native build and packaging stay outside this folder: + +- [`android/`](/android/) builds Android native artifacts +- [`apple/`](/apple/) builds Apple native artifacts + +Use `sdk` terminology only for packaged, consumer-ready layers with a stable public API. diff --git a/bindings/flutter/README.md b/bindings/flutter/README.md new file mode 100644 index 000000000..2cac52a61 --- /dev/null +++ b/bindings/flutter/README.md @@ -0,0 +1,34 @@ +# Flutter Bindings + +Dart FFI bindings to `cactus_engine.h`. + +## Integration + +```bash +cactus build --apple +cactus build --android +``` + +1. Copy `libcactus.so` to `jniLibs/arm64-v8a/` (Android) +2. Add `cactus-ios.xcframework` to your Xcode project (iOS) +3. Copy `cactus.dart` into your Dart source tree +4. Add `ffi` to `pubspec.yaml` + +## Usage + +```dart +import 'cactus.dart'; +import 'package:ffi/ffi.dart'; + +final modelPath = '/path/to/model'.toNativeUtf8(); +final model = cactusInit(modelPath, nullptr, false); +calloc.free(modelPath); + +final msgs = messagesJson.toNativeUtf8(); +final buf = calloc(65536); +cactusComplete(model, msgs, buf.cast(), 65536, nullptr, nullptr, nullptr, nullptr, nullptr, 0); +final response = buf.cast().toDartString(); +calloc.free(msgs); +calloc.free(buf); +cactusDestroy(model); +``` diff --git a/bindings/flutter/cactus.dart b/bindings/flutter/cactus.dart new file mode 100644 index 000000000..a1689b2bd --- /dev/null +++ b/bindings/flutter/cactus.dart @@ -0,0 +1,420 @@ +import 'dart:ffi'; +import 'dart:io'; + +import 'package:ffi/ffi.dart'; + +final DynamicLibrary _lib = (Platform.isAndroid || Platform.isLinux) + ? DynamicLibrary.open('libcactus.so') + : DynamicLibrary.process(); + +typedef CactusModelT = Pointer; +typedef CactusIndexT = Pointer; + +typedef TokenCallbackNative = Void Function( + Pointer token, Uint32 tokenId, Pointer userData); +typedef LogCallbackNative = Void Function( + Int32 level, Pointer component, Pointer message, + Pointer userData); + +typedef _CactusInitN = Pointer Function( + Pointer modelPath, Pointer corpusDir, Bool cacheIndex); +typedef _CactusInitD = Pointer Function( + Pointer modelPath, Pointer corpusDir, bool cacheIndex); +final cactusInit = _lib.lookupFunction<_CactusInitN, _CactusInitD>('cactus_init'); + +typedef _CactusDestroyN = Void Function(Pointer model); +typedef _CactusDestroyD = void Function(Pointer model); +final cactusDestroy = + _lib.lookupFunction<_CactusDestroyN, _CactusDestroyD>('cactus_destroy'); + +typedef _CactusResetN = Void Function(Pointer model); +typedef _CactusResetD = void Function(Pointer model); +final cactusReset = + _lib.lookupFunction<_CactusResetN, _CactusResetD>('cactus_reset'); + +typedef _CactusStopN = Void Function(Pointer model); +typedef _CactusStopD = void Function(Pointer model); +final cactusStop = + _lib.lookupFunction<_CactusStopN, _CactusStopD>('cactus_stop'); + +typedef _CactusCompleteN = Int32 Function( + Pointer model, + Pointer messagesJson, + Pointer responseBuffer, + IntPtr bufferSize, + Pointer optionsJson, + Pointer toolsJson, + Pointer> callback, + Pointer userData, + Pointer pcmBuffer, + IntPtr pcmBufferSize); +typedef _CactusCompleteD = int Function( + Pointer model, + Pointer messagesJson, + Pointer responseBuffer, + int bufferSize, + Pointer optionsJson, + Pointer toolsJson, + Pointer> callback, + Pointer userData, + Pointer pcmBuffer, + int pcmBufferSize); +final cactusComplete = + _lib.lookupFunction<_CactusCompleteN, _CactusCompleteD>('cactus_complete'); + +typedef _CactusPrefillN = Int32 Function( + Pointer model, + Pointer messagesJson, + Pointer responseBuffer, + IntPtr bufferSize, + Pointer optionsJson, + Pointer toolsJson, + Pointer pcmBuffer, + IntPtr pcmBufferSize); +typedef _CactusPrefillD = int Function( + Pointer model, + Pointer messagesJson, + Pointer responseBuffer, + int bufferSize, + Pointer optionsJson, + Pointer toolsJson, + Pointer pcmBuffer, + int pcmBufferSize); +final cactusPrefill = + _lib.lookupFunction<_CactusPrefillN, _CactusPrefillD>('cactus_prefill'); + +typedef _CactusTokenizeN = Int32 Function( + Pointer model, + Pointer text, + Pointer tokenBuffer, + IntPtr tokenBufferLen, + Pointer outTokenLen); +typedef _CactusTokenizeD = int Function( + Pointer model, + Pointer text, + Pointer tokenBuffer, + int tokenBufferLen, + Pointer outTokenLen); +final cactusTokenize = + _lib.lookupFunction<_CactusTokenizeN, _CactusTokenizeD>('cactus_tokenize'); + +typedef _CactusScoreWindowN = Int32 Function( + Pointer model, + Pointer tokens, + IntPtr tokenLen, + IntPtr start, + IntPtr end, + IntPtr context, + Pointer responseBuffer, + IntPtr bufferSize); +typedef _CactusScoreWindowD = int Function( + Pointer model, + Pointer tokens, + int tokenLen, + int start, + int end, + int context, + Pointer responseBuffer, + int bufferSize); +final cactusScoreWindow = + _lib.lookupFunction<_CactusScoreWindowN, _CactusScoreWindowD>( + 'cactus_score_window'); + +typedef _CactusTranscribeN = Int32 Function( + Pointer model, + Pointer audioFilePath, + Pointer prompt, + Pointer responseBuffer, + IntPtr bufferSize, + Pointer optionsJson, + Pointer> callback, + Pointer userData, + Pointer pcmBuffer, + IntPtr pcmBufferSize); +typedef _CactusTranscribeD = int Function( + Pointer model, + Pointer audioFilePath, + Pointer prompt, + Pointer responseBuffer, + int bufferSize, + Pointer optionsJson, + Pointer> callback, + Pointer userData, + Pointer pcmBuffer, + int pcmBufferSize); +final cactusTranscribe = + _lib.lookupFunction<_CactusTranscribeN, _CactusTranscribeD>( + 'cactus_transcribe'); + +typedef _CactusEmbedN = Int32 Function( + Pointer model, + Pointer text, + Pointer embeddingsBuffer, + IntPtr bufferSize, + Pointer embeddingDim, + Bool normalize); +typedef _CactusEmbedD = int Function( + Pointer model, + Pointer text, + Pointer embeddingsBuffer, + int bufferSize, + Pointer embeddingDim, + bool normalize); +final cactusEmbed = + _lib.lookupFunction<_CactusEmbedN, _CactusEmbedD>('cactus_embed'); + +typedef _CactusImageEmbedN = Int32 Function( + Pointer model, + Pointer imagePath, + Pointer embeddingsBuffer, + IntPtr bufferSize, + Pointer embeddingDim); +typedef _CactusImageEmbedD = int Function( + Pointer model, + Pointer imagePath, + Pointer embeddingsBuffer, + int bufferSize, + Pointer embeddingDim); +final cactusImageEmbed = + _lib.lookupFunction<_CactusImageEmbedN, _CactusImageEmbedD>( + 'cactus_image_embed'); + +typedef _CactusAudioEmbedN = Int32 Function( + Pointer model, + Pointer audioPath, + Pointer embeddingsBuffer, + IntPtr bufferSize, + Pointer embeddingDim); +typedef _CactusAudioEmbedD = int Function( + Pointer model, + Pointer audioPath, + Pointer embeddingsBuffer, + int bufferSize, + Pointer embeddingDim); +final cactusAudioEmbed = + _lib.lookupFunction<_CactusAudioEmbedN, _CactusAudioEmbedD>( + 'cactus_audio_embed'); + +typedef _CactusVadN = Int32 Function( + Pointer model, + Pointer audioFilePath, + Pointer responseBuffer, + IntPtr bufferSize, + Pointer optionsJson, + Pointer pcmBuffer, + IntPtr pcmBufferSize); +typedef _CactusVadD = int Function( + Pointer model, + Pointer audioFilePath, + Pointer responseBuffer, + int bufferSize, + Pointer optionsJson, + Pointer pcmBuffer, + int pcmBufferSize); +final cactusVad = + _lib.lookupFunction<_CactusVadN, _CactusVadD>('cactus_vad'); + +typedef _CactusDiarizeN = Int32 Function( + Pointer model, + Pointer audioFilePath, + Pointer responseBuffer, + IntPtr bufferSize, + Pointer optionsJson, + Pointer pcmBuffer, + IntPtr pcmBufferSize); +typedef _CactusDiarizeD = int Function( + Pointer model, + Pointer audioFilePath, + Pointer responseBuffer, + int bufferSize, + Pointer optionsJson, + Pointer pcmBuffer, + int pcmBufferSize); +final cactusDiarize = + _lib.lookupFunction<_CactusDiarizeN, _CactusDiarizeD>('cactus_diarize'); + +typedef _CactusEmbedSpeakerN = Int32 Function( + Pointer model, + Pointer audioFilePath, + Pointer responseBuffer, + IntPtr bufferSize, + Pointer optionsJson, + Pointer pcmBuffer, + IntPtr pcmBufferSize, + Pointer maskWeights, + IntPtr maskNumFrames); +typedef _CactusEmbedSpeakerD = int Function( + Pointer model, + Pointer audioFilePath, + Pointer responseBuffer, + int bufferSize, + Pointer optionsJson, + Pointer pcmBuffer, + int pcmBufferSize, + Pointer maskWeights, + int maskNumFrames); +final cactusEmbedSpeaker = + _lib.lookupFunction<_CactusEmbedSpeakerN, _CactusEmbedSpeakerD>( + 'cactus_embed_speaker'); + +typedef _CactusRagQueryN = Int32 Function( + Pointer model, + Pointer query, + Pointer responseBuffer, + IntPtr bufferSize, + IntPtr topK); +typedef _CactusRagQueryD = int Function( + Pointer model, + Pointer query, + Pointer responseBuffer, + int bufferSize, + int topK); +final cactusRagQuery = + _lib.lookupFunction<_CactusRagQueryN, _CactusRagQueryD>( + 'cactus_rag_query'); + +typedef _CactusIndexInitN = Pointer Function( + Pointer indexDir, IntPtr embeddingDim); +typedef _CactusIndexInitD = Pointer Function( + Pointer indexDir, int embeddingDim); +final cactusIndexInit = + _lib.lookupFunction<_CactusIndexInitN, _CactusIndexInitD>( + 'cactus_index_init'); + +typedef _CactusIndexAddN = Int32 Function( + Pointer index, + Pointer ids, + Pointer> documents, + Pointer> metadatas, + Pointer> embeddings, + IntPtr count, + IntPtr embeddingDim); +typedef _CactusIndexAddD = int Function( + Pointer index, + Pointer ids, + Pointer> documents, + Pointer> metadatas, + Pointer> embeddings, + int count, + int embeddingDim); +final cactusIndexAdd = + _lib.lookupFunction<_CactusIndexAddN, _CactusIndexAddD>( + 'cactus_index_add'); + +typedef _CactusIndexDeleteN = Int32 Function( + Pointer index, Pointer ids, IntPtr idsCount); +typedef _CactusIndexDeleteD = int Function( + Pointer index, Pointer ids, int idsCount); +final cactusIndexDelete = + _lib.lookupFunction<_CactusIndexDeleteN, _CactusIndexDeleteD>( + 'cactus_index_delete'); + +typedef _CactusIndexGetN = Int32 Function( + Pointer index, + Pointer ids, + IntPtr idsCount, + Pointer> documentBuffers, + Pointer documentBufferSizes, + Pointer> metadataBuffers, + Pointer metadataBufferSizes, + Pointer> embeddingBuffers, + Pointer embeddingBufferSizes); +typedef _CactusIndexGetD = int Function( + Pointer index, + Pointer ids, + int idsCount, + Pointer> documentBuffers, + Pointer documentBufferSizes, + Pointer> metadataBuffers, + Pointer metadataBufferSizes, + Pointer> embeddingBuffers, + Pointer embeddingBufferSizes); +final cactusIndexGet = + _lib.lookupFunction<_CactusIndexGetN, _CactusIndexGetD>( + 'cactus_index_get'); + +typedef _CactusIndexQueryN = Int32 Function( + Pointer index, + Pointer> embeddings, + IntPtr embeddingsCount, + IntPtr embeddingDim, + Pointer optionsJson, + Pointer> idBuffers, + Pointer idBufferSizes, + Pointer> scoreBuffers, + Pointer scoreBufferSizes); +typedef _CactusIndexQueryD = int Function( + Pointer index, + Pointer> embeddings, + int embeddingsCount, + int embeddingDim, + Pointer optionsJson, + Pointer> idBuffers, + Pointer idBufferSizes, + Pointer> scoreBuffers, + Pointer scoreBufferSizes); +final cactusIndexQuery = + _lib.lookupFunction<_CactusIndexQueryN, _CactusIndexQueryD>( + 'cactus_index_query'); + +typedef _CactusIndexCompactN = Int32 Function(Pointer index); +typedef _CactusIndexCompactD = int Function(Pointer index); +final cactusIndexCompact = + _lib.lookupFunction<_CactusIndexCompactN, _CactusIndexCompactD>( + 'cactus_index_compact'); + +typedef _CactusIndexDestroyN = Void Function(Pointer index); +typedef _CactusIndexDestroyD = void Function(Pointer index); +final cactusIndexDestroy = + _lib.lookupFunction<_CactusIndexDestroyN, _CactusIndexDestroyD>( + 'cactus_index_destroy'); + +typedef _CactusGetLastErrorN = Pointer Function(); +typedef _CactusGetLastErrorD = Pointer Function(); +final cactusGetLastError = + _lib.lookupFunction<_CactusGetLastErrorN, _CactusGetLastErrorD>( + 'cactus_get_last_error'); + +typedef _CactusLogSetLevelN = Void Function(Int32 level); +typedef _CactusLogSetLevelD = void Function(int level); +final cactusLogSetLevel = + _lib.lookupFunction<_CactusLogSetLevelN, _CactusLogSetLevelD>( + 'cactus_log_set_level'); + +typedef _CactusLogSetCallbackN = Void Function( + Pointer> callback, + Pointer userData); +typedef _CactusLogSetCallbackD = void Function( + Pointer> callback, + Pointer userData); +final cactusLogSetCallback = + _lib.lookupFunction<_CactusLogSetCallbackN, _CactusLogSetCallbackD>( + 'cactus_log_set_callback'); + +typedef _CactusSetTelemetryEnvironmentN = Void Function( + Pointer framework, Pointer cacheLocation, + Pointer version); +typedef _CactusSetTelemetryEnvironmentD = void Function( + Pointer framework, Pointer cacheLocation, + Pointer version); +final cactusSetTelemetryEnvironment = _lib.lookupFunction< + _CactusSetTelemetryEnvironmentN, + _CactusSetTelemetryEnvironmentD>('cactus_set_telemetry_environment'); + +typedef _CactusSetAppIdN = Void Function(Pointer appId); +typedef _CactusSetAppIdD = void Function(Pointer appId); +final cactusSetAppId = + _lib.lookupFunction<_CactusSetAppIdN, _CactusSetAppIdD>( + 'cactus_set_app_id'); + +typedef _CactusTelemetryFlushN = Void Function(); +typedef _CactusTelemetryFlushD = void Function(); +final cactusTelemetryFlush = + _lib.lookupFunction<_CactusTelemetryFlushN, _CactusTelemetryFlushD>( + 'cactus_telemetry_flush'); + +typedef _CactusTelemetryShutdownN = Void Function(); +typedef _CactusTelemetryShutdownD = void Function(); +final cactusTelemetryShutdown = + _lib.lookupFunction<_CactusTelemetryShutdownN, _CactusTelemetryShutdownD>( + 'cactus_telemetry_shutdown'); diff --git a/bindings/kotlin/Cactus.android.kt b/bindings/kotlin/Cactus.android.kt new file mode 100644 index 000000000..7e2c8986b --- /dev/null +++ b/bindings/kotlin/Cactus.android.kt @@ -0,0 +1,156 @@ +package com.cactus + +private fun check(rc: Int) { + if (rc < 0) throw RuntimeException(CactusJNI.nativeGetLastError().ifEmpty { "Unknown error" }) +} + +actual fun cactusInit(modelPath: String, corpusDir: String?, cacheIndex: Boolean): Long { + val handle = CactusJNI.nativeInit(modelPath, corpusDir, cacheIndex) + if (handle == 0L) throw RuntimeException(CactusJNI.nativeGetLastError().ifEmpty { "Failed to initialize model" }) + return handle +} + +actual fun cactusDestroy(handle: Long) = CactusJNI.nativeDestroy(handle) +actual fun cactusReset(handle: Long) = CactusJNI.nativeReset(handle) +actual fun cactusStop(handle: Long) = CactusJNI.nativeStop(handle) + +actual fun cactusComplete(handle: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String { + val buffer = ByteArray(1024 * 1024) + check(CactusJNI.nativeComplete(handle, messagesJson, buffer, optionsJson, toolsJson, callback, pcmData)) + return buffer.decodeToString().trimEnd('\u0000') +} + +actual fun cactusPrefill(handle: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, pcmData: ByteArray?): String { + val buffer = ByteArray(1024 * 1024) + check(CactusJNI.nativePrefill(handle, messagesJson, buffer, optionsJson, toolsJson, pcmData)) + return buffer.decodeToString().trimEnd('\u0000') +} + +actual fun cactusTokenize(handle: Long, text: String): IntArray { + val tokenBuffer = IntArray(8192) + val outLen = LongArray(1) + check(CactusJNI.nativeTokenize(handle, text, tokenBuffer, outLen)) + return tokenBuffer.copyOf(outLen[0].toInt()) +} + +actual fun cactusScoreWindow(handle: Long, tokens: IntArray, start: Long, end: Long, context: Long): String { + val buffer = ByteArray(1024 * 1024) + check(CactusJNI.nativeScoreWindow(handle, tokens, start, end, context, buffer)) + return buffer.decodeToString().trimEnd('\u0000') +} + +actual fun cactusTranscribe(handle: Long, audioPath: String?, prompt: String, optionsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String { + val buffer = ByteArray(1024 * 1024) + check(CactusJNI.nativeTranscribe(handle, audioPath, prompt, buffer, optionsJson, callback, pcmData)) + return buffer.decodeToString().trimEnd('\u0000') +} + +actual fun cactusEmbed(handle: Long, text: String, normalize: Boolean): FloatArray { + val buffer = FloatArray(4096) + val outDim = LongArray(1) + check(CactusJNI.nativeEmbed(handle, text, buffer, outDim, normalize)) + return buffer.copyOf(outDim[0].toInt()) +} + +actual fun cactusImageEmbed(handle: Long, imagePath: String): FloatArray { + val buffer = FloatArray(4096) + val outDim = LongArray(1) + check(CactusJNI.nativeImageEmbed(handle, imagePath, buffer, outDim)) + return buffer.copyOf(outDim[0].toInt()) +} + +actual fun cactusAudioEmbed(handle: Long, audioPath: String): FloatArray { + val buffer = FloatArray(4096) + val outDim = LongArray(1) + check(CactusJNI.nativeAudioEmbed(handle, audioPath, buffer, outDim)) + return buffer.copyOf(outDim[0].toInt()) +} + +actual fun cactusVad(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String { + val buffer = ByteArray(1024 * 1024) + check(CactusJNI.nativeVad(handle, audioPath, buffer, optionsJson, pcmData)) + return buffer.decodeToString().trimEnd('\u0000') +} + +actual fun cactusDiarize(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String { + val buffer = ByteArray(1024 * 1024) + check(CactusJNI.nativeDiarize(handle, audioPath, buffer, optionsJson, pcmData)) + return buffer.decodeToString().trimEnd('\u0000') +} + +actual fun cactusEmbedSpeaker(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?, maskWeights: FloatArray?, maskNumFrames: Long): String { + val buffer = ByteArray(1024 * 1024) + check(CactusJNI.nativeEmbedSpeaker(handle, audioPath, buffer, optionsJson, pcmData, maskWeights, maskNumFrames)) + return buffer.decodeToString().trimEnd('\u0000') +} + +actual fun cactusRagQuery(handle: Long, query: String, topK: Long): String { + val buffer = ByteArray(1024 * 1024) + check(CactusJNI.nativeRagQuery(handle, query, buffer, topK)) + return buffer.decodeToString().trimEnd('\u0000') +} + +actual fun cactusIndexInit(indexDir: String, embeddingDim: Long): Long { + val handle = CactusJNI.nativeIndexInit(indexDir, embeddingDim) + if (handle == 0L) throw RuntimeException(CactusJNI.nativeGetLastError().ifEmpty { "Failed to initialize index" }) + return handle +} + +actual fun cactusIndexAdd(handle: Long, ids: IntArray, documents: Array, metadatas: Array?, embeddings: Array, embeddingDim: Long): Int { + val rc = CactusJNI.nativeIndexAdd(handle, ids, documents, metadatas, embeddings, embeddingDim) + check(rc) + return rc +} + +actual fun cactusIndexDelete(handle: Long, ids: IntArray): Int { + val rc = CactusJNI.nativeIndexDelete(handle, ids) + check(rc) + return rc +} + +actual fun cactusIndexGet(handle: Long, ids: IntArray): String { + val count = ids.size + val docBuffers = Array(count) { ByteArray(4096) } + val docSizes = LongArray(count) { 4096L } + val metaBuffers = Array(count) { ByteArray(4096) } + val metaSizes = LongArray(count) { 4096L } + val embBuffers = Array(count) { FloatArray(4096) } + val embSizes = LongArray(count) { 4096L } + check(CactusJNI.nativeIndexGet(handle, ids, docBuffers, docSizes, metaBuffers, metaSizes, embBuffers, embSizes)) + val results = ids.indices.map { i -> + val doc = docBuffers[i].decodeToString().trimEnd('\u0000') + val meta = metaBuffers[i].decodeToString().trimEnd('\u0000') + """{"document":"$doc","metadata":"$meta"}""" + } + return """{"results":[${results.joinToString(",")}]}""" +} + +actual fun cactusIndexQuery(handle: Long, embedding: FloatArray, optionsJson: String?): String { + val idBuffers = arrayOf(IntArray(1000)) + val idSizes = longArrayOf(1000L) + val scoreBuffers = arrayOf(FloatArray(1000)) + val scoreSizes = longArrayOf(1000L) + check(CactusJNI.nativeIndexQuery(handle, arrayOf(embedding), embedding.size.toLong(), optionsJson, idBuffers, idSizes, scoreBuffers, scoreSizes)) + val results = (0 until idSizes[0].toInt()).map { i -> + """{"id":${idBuffers[0][i]},"score":${scoreBuffers[0][i]}}""" + } + return """{"results":[${results.joinToString(",")}]}""" +} + +actual fun cactusIndexCompact(handle: Long): Int { + val rc = CactusJNI.nativeIndexCompact(handle) + check(rc) + return rc +} + +actual fun cactusIndexDestroy(handle: Long) = CactusJNI.nativeIndexDestroy(handle) +actual fun cactusGetLastError(): String = CactusJNI.nativeGetLastError() +actual fun cactusLogSetLevel(level: Int) = CactusJNI.nativeLogSetLevel(level) +actual fun cactusLogSetCallback(callback: CactusLogCallback?) = CactusJNI.nativeLogSetCallback(callback) + +actual fun cactusSetTelemetryEnvironment(framework: String?, cacheLocation: String?, version: String?) = + CactusJNI.nativeSetTelemetryEnvironment(framework, cacheLocation, version) + +actual fun cactusSetAppId(appId: String) = CactusJNI.nativeSetAppId(appId) +actual fun cactusTelemetryFlush() = CactusJNI.nativeTelemetryFlush() +actual fun cactusTelemetryShutdown() = CactusJNI.nativeTelemetryShutdown() diff --git a/bindings/kotlin/Cactus.common.kt b/bindings/kotlin/Cactus.common.kt new file mode 100644 index 000000000..f1e88d47a --- /dev/null +++ b/bindings/kotlin/Cactus.common.kt @@ -0,0 +1,32 @@ +package com.cactus + +expect fun cactusInit(modelPath: String, corpusDir: String?, cacheIndex: Boolean): Long +expect fun cactusDestroy(handle: Long) +expect fun cactusReset(handle: Long) +expect fun cactusStop(handle: Long) +expect fun cactusComplete(handle: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String +expect fun cactusPrefill(handle: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, pcmData: ByteArray?): String +expect fun cactusTokenize(handle: Long, text: String): IntArray +expect fun cactusScoreWindow(handle: Long, tokens: IntArray, start: Long, end: Long, context: Long): String +expect fun cactusTranscribe(handle: Long, audioPath: String?, prompt: String, optionsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String +expect fun cactusEmbed(handle: Long, text: String, normalize: Boolean): FloatArray +expect fun cactusImageEmbed(handle: Long, imagePath: String): FloatArray +expect fun cactusAudioEmbed(handle: Long, audioPath: String): FloatArray +expect fun cactusVad(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String +expect fun cactusDiarize(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String +expect fun cactusEmbedSpeaker(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?, maskWeights: FloatArray?, maskNumFrames: Long): String +expect fun cactusRagQuery(handle: Long, query: String, topK: Long): String +expect fun cactusIndexInit(indexDir: String, embeddingDim: Long): Long +expect fun cactusIndexAdd(handle: Long, ids: IntArray, documents: Array, metadatas: Array?, embeddings: Array, embeddingDim: Long): Int +expect fun cactusIndexDelete(handle: Long, ids: IntArray): Int +expect fun cactusIndexGet(handle: Long, ids: IntArray): String +expect fun cactusIndexQuery(handle: Long, embedding: FloatArray, optionsJson: String?): String +expect fun cactusIndexCompact(handle: Long): Int +expect fun cactusIndexDestroy(handle: Long) +expect fun cactusGetLastError(): String +expect fun cactusLogSetLevel(level: Int) +expect fun cactusLogSetCallback(callback: CactusLogCallback?) +expect fun cactusSetTelemetryEnvironment(framework: String?, cacheLocation: String?, version: String?) +expect fun cactusSetAppId(appId: String) +expect fun cactusTelemetryFlush() +expect fun cactusTelemetryShutdown() diff --git a/bindings/kotlin/Cactus.ios.kt b/bindings/kotlin/Cactus.ios.kt new file mode 100644 index 000000000..083d1cf09 --- /dev/null +++ b/bindings/kotlin/Cactus.ios.kt @@ -0,0 +1,371 @@ +package com.cactus + +import cactus.* +import kotlinx.cinterop.* + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusInit(modelPath: String, corpusDir: String?, cacheIndex: Boolean): Long { + val ptr = cactus_init(modelPath, corpusDir, cacheIndex) + ?: throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Failed to initialize model") + return ptr.rawValue.toLong() +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusDestroy(handle: Long) { + cactus_destroy(handle.toCPointer()) +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusReset(handle: Long) { cactus_reset(handle.toCPointer()) } + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusStop(handle: Long) { cactus_stop(handle.toCPointer()) } + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusComplete(handle: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String { + memScoped { + val buffer = allocArray(1048576) + val callbackRef = callback?.let { StableRef.create(it) } + val pcmPtr = pcmData?.refTo(0)?.getPointer(this) + try { + val result = cactus_complete( + handle.toCPointer(), + messagesJson, + buffer, + 1048576u, + optionsJson, + toolsJson, + callbackRef?.let { + staticCFunction?, UInt, COpaquePointer?, Unit> { token, tokenId, userData -> + if (token != null && userData != null) { + userData.asStableRef().get().onToken(token.toKString(), tokenId.toInt()) + } + } + }, + callbackRef?.asCPointer(), + pcmPtr?.reinterpret(), + pcmData?.size?.toULong() ?: 0u + ) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return buffer.toKString() + } finally { + callbackRef?.dispose() + } + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusPrefill(handle: Long, messagesJson: String, optionsJson: String?, toolsJson: String?, pcmData: ByteArray?): String { + memScoped { + val buffer = allocArray(1048576) + val pcmPtr = pcmData?.refTo(0)?.getPointer(this) + val result = cactus_prefill( + handle.toCPointer(), + messagesJson, + buffer, + 1048576u, + optionsJson, + toolsJson, + pcmPtr?.reinterpret(), + pcmData?.size?.toULong() ?: 0u + ) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return buffer.toKString() + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusTokenize(handle: Long, text: String): IntArray { + memScoped { + val buffer = allocArray(8192) + val tokenLen = alloc() + val result = cactus_tokenize(handle.toCPointer(), text, buffer, 8192u, tokenLen.ptr) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return IntArray(tokenLen.value.toInt()) { buffer[it].toInt() } + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusScoreWindow(handle: Long, tokens: IntArray, start: Long, end: Long, context: Long): String { + memScoped { + val buffer = allocArray(1048576) + val tokenBuffer = allocArray(tokens.size) + tokens.forEachIndexed { i, v -> tokenBuffer[i] = v.toUInt() } + val result = cactus_score_window( + handle.toCPointer(), tokenBuffer, tokens.size.toULong(), + start.toULong(), end.toULong(), context.toULong(), + buffer, 1048576u + ) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return buffer.toKString() + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusTranscribe(handle: Long, audioPath: String?, prompt: String, optionsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): String { + memScoped { + val buffer = allocArray(1048576) + val callbackRef = callback?.let { StableRef.create(it) } + val pcmPtr = pcmData?.refTo(0)?.getPointer(this) + try { + val result = cactus_transcribe( + handle.toCPointer(), + audioPath, + prompt, + buffer, + 1048576u, + optionsJson, + callbackRef?.let { + staticCFunction?, UInt, COpaquePointer?, Unit> { token, tokenId, userData -> + if (token != null && userData != null) { + userData.asStableRef().get().onToken(token.toKString(), tokenId.toInt()) + } + } + }, + callbackRef?.asCPointer(), + pcmPtr?.reinterpret(), + pcmData?.size?.toULong() ?: 0u + ) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return buffer.toKString() + } finally { + callbackRef?.dispose() + } + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusEmbed(handle: Long, text: String, normalize: Boolean): FloatArray { + memScoped { + val buffer = allocArray(4096) + val dimPtr = alloc() + val result = cactus_embed(handle.toCPointer(), text, buffer, 4096u, dimPtr.ptr, normalize) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return FloatArray(dimPtr.value.toInt()) { buffer[it] } + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusImageEmbed(handle: Long, imagePath: String): FloatArray { + memScoped { + val buffer = allocArray(4096) + val dimPtr = alloc() + val result = cactus_image_embed(handle.toCPointer(), imagePath, buffer, 4096u, dimPtr.ptr) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return FloatArray(dimPtr.value.toInt()) { buffer[it] } + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusAudioEmbed(handle: Long, audioPath: String): FloatArray { + memScoped { + val buffer = allocArray(4096) + val dimPtr = alloc() + val result = cactus_audio_embed(handle.toCPointer(), audioPath, buffer, 4096u, dimPtr.ptr) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return FloatArray(dimPtr.value.toInt()) { buffer[it] } + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusVad(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String { + memScoped { + val buffer = allocArray(1048576) + val pcmPtr = pcmData?.refTo(0)?.getPointer(this) + val result = cactus_vad( + handle.toCPointer(), audioPath, buffer, 1048576u, optionsJson, + pcmPtr?.reinterpret(), pcmData?.size?.toULong() ?: 0u + ) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return buffer.toKString() + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusDiarize(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?): String { + memScoped { + val buffer = allocArray(1048576) + val pcmPtr = pcmData?.refTo(0)?.getPointer(this) + val result = cactus_diarize( + handle.toCPointer(), audioPath, buffer, 1048576u, optionsJson, + pcmPtr?.reinterpret(), pcmData?.size?.toULong() ?: 0u + ) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return buffer.toKString() + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusEmbedSpeaker(handle: Long, audioPath: String?, optionsJson: String?, pcmData: ByteArray?, maskWeights: FloatArray?, maskNumFrames: Long): String { + memScoped { + val buffer = allocArray(1048576) + val pcmPtr = pcmData?.refTo(0)?.getPointer(this) + val maskPtr = maskWeights?.let { + val arr = allocArray(it.size) + it.forEachIndexed { i, v -> arr[i] = v } + arr + } + val result = cactus_embed_speaker( + handle.toCPointer(), audioPath, buffer, 1048576u, optionsJson, + pcmPtr?.reinterpret(), pcmData?.size?.toULong() ?: 0u, + maskPtr, maskNumFrames.toULong() + ) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return buffer.toKString() + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusRagQuery(handle: Long, query: String, topK: Long): String { + memScoped { + val buffer = allocArray(1048576) + val result = cactus_rag_query(handle.toCPointer(), query, buffer, 1048576u, topK.toULong()) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return buffer.toKString() + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusIndexInit(indexDir: String, embeddingDim: Long): Long { + val ptr = cactus_index_init(indexDir, embeddingDim.toULong()) + ?: throw RuntimeException("Failed to initialize index") + return ptr.rawValue.toLong() +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusIndexAdd(handle: Long, ids: IntArray, documents: Array, metadatas: Array?, embeddings: Array, embeddingDim: Long): Int { + memScoped { + val idPtr = allocArray(ids.size) + ids.forEachIndexed { i, v -> idPtr[i] = v } + val docPtrs = allocArray>(documents.size) + documents.forEachIndexed { i, doc -> docPtrs[i] = doc.cstr.ptr } + val metaPtrs = metadatas?.let { + val ptrs = allocArray>(it.size) + it.forEachIndexed { i, meta -> ptrs[i] = meta.cstr.ptr } + ptrs + } + val embPtrs = allocArray>(embeddings.size) + embeddings.forEachIndexed { i, emb -> + val embArr = allocArray(emb.size) + emb.forEachIndexed { j, v -> embArr[j] = v } + embPtrs[i] = embArr + } + val result = cactus_index_add( + handle.toCPointer(), idPtr, docPtrs, metaPtrs, embPtrs, + ids.size.toULong(), embeddingDim.toULong() + ) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return result + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusIndexDelete(handle: Long, ids: IntArray): Int { + memScoped { + val idPtr = allocArray(ids.size) + ids.forEachIndexed { i, v -> idPtr[i] = v } + val result = cactus_index_delete(handle.toCPointer(), idPtr, ids.size.toULong()) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return result + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusIndexGet(handle: Long, ids: IntArray): String { + memScoped { + val count = ids.size + val idPtr = allocArray(count) + ids.forEachIndexed { i, v -> idPtr[i] = v } + val docBufs = allocArray>(count) + val docSizes = allocArray(count) + val metaBufs = allocArray>(count) + val metaSizes = allocArray(count) + val embBufs = allocArray>(count) + val embSizes = allocArray(count) + val docAllocs = (0 until count).map { allocArray(4096) } + val metaAllocs = (0 until count).map { allocArray(4096) } + val embAllocs = (0 until count).map { allocArray(4096) } + for (i in 0 until count) { + docBufs[i] = docAllocs[i]; docSizes[i] = 4096u + metaBufs[i] = metaAllocs[i]; metaSizes[i] = 4096u + embBufs[i] = embAllocs[i]; embSizes[i] = 4096u + } + cactus_index_get(handle.toCPointer(), idPtr, count.toULong(), docBufs, docSizes, metaBufs, metaSizes, embBufs, embSizes) + val results = (0 until count).map { i -> + val doc = docAllocs[i].toKString() + val meta = metaAllocs[i].toKString() + """{"document":"$doc","metadata":"$meta"}""" + } + return """{"results":[${results.joinToString(",")}]}""" + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusIndexQuery(handle: Long, embedding: FloatArray, optionsJson: String?): String { + memScoped { + val embArr = allocArray(embedding.size) + embedding.forEachIndexed { i, v -> embArr[i] = v } + val embPtrs = allocArray>(1) + embPtrs[0] = embArr + val idBuf = allocArray(1000) + val idPtrs = allocArray>(1) + idPtrs[0] = idBuf + val idSizes = allocArray(1); idSizes[0] = 1000u + val scoreBuf = allocArray(1000) + val scorePtrs = allocArray>(1) + scorePtrs[0] = scoreBuf + val scoreSizes = allocArray(1); scoreSizes[0] = 1000u + cactus_index_query(handle.toCPointer(), embPtrs, 1u, embedding.size.toULong(), optionsJson, idPtrs, idSizes, scorePtrs, scoreSizes) + val results = (0 until idSizes[0].toInt()).map { i -> + """{"id":${idBuf[i]},"score":${scoreBuf[i]}}""" + } + return """{"results":[${results.joinToString(",")}]}""" + } +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusIndexCompact(handle: Long): Int { + val result = cactus_index_compact(handle.toCPointer()) + if (result < 0) throw RuntimeException(cactus_get_last_error()?.toKString() ?: "Unknown error") + return result +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusIndexDestroy(handle: Long) { + cactus_index_destroy(handle.toCPointer()) +} + +actual fun cactusGetLastError(): String = cactus_get_last_error()?.toKString() ?: "" + +actual fun cactusLogSetLevel(level: Int) { + cactus_log_set_level(level) +} + +private var _logCallbackRef: StableRef? = null + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusLogSetCallback(callback: CactusLogCallback?) { + _logCallbackRef?.dispose() + _logCallbackRef = null + if (callback == null) { + cactus_log_set_callback(null, null) + return + } + val ref = StableRef.create(callback) + _logCallbackRef = ref + cactus_log_set_callback(staticCFunction { level, component, message, userData -> + val cb = userData!!.asStableRef().get() + cb.onLog(level, component?.toKString() ?: "", message?.toKString() ?: "") + }, ref.asCPointer()) +} + +@OptIn(ExperimentalForeignApi::class) +actual fun cactusSetTelemetryEnvironment(framework: String?, cacheLocation: String?, version: String?) { + cactus_set_telemetry_environment(framework, cacheLocation, version) +} + +actual fun cactusSetAppId(appId: String) { cactus_set_app_id(appId) } + +actual fun cactusTelemetryFlush() { cactus_telemetry_flush() } + +actual fun cactusTelemetryShutdown() { cactus_telemetry_shutdown() } diff --git a/bindings/kotlin/Cactus.kt b/bindings/kotlin/Cactus.kt new file mode 100644 index 000000000..76cbe1dac --- /dev/null +++ b/bindings/kotlin/Cactus.kt @@ -0,0 +1,46 @@ +package com.cactus + +fun interface CactusTokenCallback { + fun onToken(token: String, tokenId: Int) +} + +fun interface CactusLogCallback { + fun onLog(level: Int, component: String, message: String) +} + +object CactusJNI { + init { + System.loadLibrary("cactus") + } + + @JvmStatic external fun nativeInit(modelPath: String, corpusDir: String?, cacheIndex: Boolean): Long + @JvmStatic external fun nativeDestroy(handle: Long) + @JvmStatic external fun nativeReset(handle: Long) + @JvmStatic external fun nativeStop(handle: Long) + @JvmStatic external fun nativeComplete(handle: Long, messagesJson: String, responseBuffer: ByteArray, optionsJson: String?, toolsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): Int + @JvmStatic external fun nativePrefill(handle: Long, messagesJson: String, responseBuffer: ByteArray, optionsJson: String?, toolsJson: String?, pcmData: ByteArray?): Int + @JvmStatic external fun nativeTokenize(handle: Long, text: String, tokenBuffer: IntArray, outTokenLen: LongArray): Int + @JvmStatic external fun nativeScoreWindow(handle: Long, tokens: IntArray, start: Long, end: Long, context: Long, responseBuffer: ByteArray): Int + @JvmStatic external fun nativeTranscribe(handle: Long, audioPath: String?, prompt: String, responseBuffer: ByteArray, optionsJson: String?, callback: CactusTokenCallback?, pcmData: ByteArray?): Int + @JvmStatic external fun nativeEmbed(handle: Long, text: String, embeddingsBuffer: FloatArray, outEmbeddingDim: LongArray, normalize: Boolean): Int + @JvmStatic external fun nativeImageEmbed(handle: Long, imagePath: String, embeddingsBuffer: FloatArray, outEmbeddingDim: LongArray): Int + @JvmStatic external fun nativeAudioEmbed(handle: Long, audioPath: String, embeddingsBuffer: FloatArray, outEmbeddingDim: LongArray): Int + @JvmStatic external fun nativeVad(handle: Long, audioPath: String?, responseBuffer: ByteArray, optionsJson: String?, pcmData: ByteArray?): Int + @JvmStatic external fun nativeDiarize(handle: Long, audioPath: String?, responseBuffer: ByteArray, optionsJson: String?, pcmData: ByteArray?): Int + @JvmStatic external fun nativeEmbedSpeaker(handle: Long, audioPath: String?, responseBuffer: ByteArray, optionsJson: String?, pcmData: ByteArray?, maskWeights: FloatArray?, maskNumFrames: Long): Int + @JvmStatic external fun nativeRagQuery(handle: Long, query: String, responseBuffer: ByteArray, topK: Long): Int + @JvmStatic external fun nativeIndexInit(indexDir: String, embeddingDim: Long): Long + @JvmStatic external fun nativeIndexAdd(handle: Long, ids: IntArray, documents: Array, metadatas: Array?, embeddings: Array, embeddingDim: Long): Int + @JvmStatic external fun nativeIndexDelete(handle: Long, ids: IntArray): Int + @JvmStatic external fun nativeIndexGet(handle: Long, ids: IntArray, documentBuffers: Array, documentBufferSizes: LongArray, metadataBuffers: Array, metadataBufferSizes: LongArray, embeddingBuffers: Array, embeddingBufferSizes: LongArray): Int + @JvmStatic external fun nativeIndexQuery(handle: Long, embeddings: Array, embeddingDim: Long, optionsJson: String?, idBuffers: Array, idBufferSizes: LongArray, scoreBuffers: Array, scoreBufferSizes: LongArray): Int + @JvmStatic external fun nativeIndexCompact(handle: Long): Int + @JvmStatic external fun nativeIndexDestroy(handle: Long) + @JvmStatic external fun nativeGetLastError(): String + @JvmStatic external fun nativeLogSetLevel(level: Int) + @JvmStatic external fun nativeLogSetCallback(callback: CactusLogCallback?) + @JvmStatic external fun nativeSetTelemetryEnvironment(framework: String?, cacheLocation: String?, version: String?) + @JvmStatic external fun nativeSetAppId(appId: String) + @JvmStatic external fun nativeTelemetryFlush() + @JvmStatic external fun nativeTelemetryShutdown() +} diff --git a/bindings/kotlin/README.md b/bindings/kotlin/README.md new file mode 100644 index 000000000..10f0d5dff --- /dev/null +++ b/bindings/kotlin/README.md @@ -0,0 +1,58 @@ +# Kotlin Bindings + +JNI bridge to `cactus_engine.h` for Android, with KMP support for iOS. + +## Android Integration + +```bash +cactus build --android +``` + +1. Copy `android/libcactus.so` to `app/src/main/jniLibs/arm64-v8a/` +2. Copy `Cactus.kt` to your Kotlin source tree + +```kotlin +val handle = CactusJNI.nativeInit("/path/to/model", null, false) +val buf = ByteArray(65536) +CactusJNI.nativeComplete(handle, messagesJson, buf, null, null, null, null) +val response = String(buf, 0, buf.indexOf(0)) +CactusJNI.nativeDestroy(handle) +``` + +## Kotlin Multiplatform + +``` +commonMain/ Cactus.common.kt expect declarations +androidMain/ Cactus.android.kt actual via JNI +iosMain/ Cactus.ios.kt actual via cinterop +``` + +### build.gradle.kts + +```kotlin +kotlin { + androidTarget() + + listOf(iosArm64(), iosSimulatorArm64()).forEach { + it.compilations.getByName("main") { + cinterops { + val cactus by creating { + defFile("src/nativeInterop/cinterop/cactus.def") + includeDirs("/path/to/cactus/cactus-engine") + } + } + } + it.binaries.framework { + linkerOpts("-L/path/to/cactus/apple", "-lcactus-device") + } + } +} +``` + +### Usage (shared code) + +```kotlin +val model = cactusInit("/path/to/model", null, false) +val result = cactusComplete(model, messagesJson, null, null, null) +cactusDestroy(model) +``` diff --git a/bindings/kotlin/cactus.def b/bindings/kotlin/cactus.def new file mode 100644 index 000000000..32086abd6 --- /dev/null +++ b/bindings/kotlin/cactus.def @@ -0,0 +1,3 @@ +package = cactus +headers = cactus_engine.h +headerFilter = cactus_engine.h diff --git a/bindings/python/README.md b/bindings/python/README.md new file mode 100644 index 000000000..8e5f71fa6 --- /dev/null +++ b/bindings/python/README.md @@ -0,0 +1,20 @@ +# Python Bindings + +ctypes FFI bindings to `cactus_engine.h`. + +## Integration + +```bash +cactus build --python +pip install -e python/ +``` + +## Usage + +```python +from cactus.bindings import cactus + +model = cactus.cactus_init("/path/to/model", None, False) +response = cactus.cactus_complete(model, messages_json, None, None, None) +cactus.cactus_destroy(model) +``` diff --git a/bindings/react-native/README.md b/bindings/react-native/README.md new file mode 100644 index 000000000..fbd4561f6 --- /dev/null +++ b/bindings/react-native/README.md @@ -0,0 +1,29 @@ +# React Native Bindings + +Native bridge modules over the cactus C API for iOS and Android. + +## Integration + +```bash +cactus build --apple +cactus build --android +``` + +1. Add the bridge files from this folder to your React Native app +2. Add the raw bindings they depend on: [`bindings/kotlin/`](/bindings/kotlin/) (Android), [`bindings/swift/`](/bindings/swift/) (Apple) +3. Register the Android package in `MainApplication.kt`: + ```kotlin + override fun getPackages() = PackageList(this).packages.apply { + add(com.cactus.reactnative.CactusPackage()) + } + ``` + +## Usage + +```ts +import Cactus from './index'; + +const handle = await Cactus.init('/path/to/model', null, false); +const result = await Cactus.complete(handle, messagesJson, null, null, null); +await Cactus.destroy(handle); +``` diff --git a/bindings/react-native/android/CactusModule.kt b/bindings/react-native/android/CactusModule.kt new file mode 100644 index 000000000..eb02ce147 --- /dev/null +++ b/bindings/react-native/android/CactusModule.kt @@ -0,0 +1,500 @@ +package com.cactus.reactnative + +import android.util.Base64 +import com.cactus.CactusJNI +import com.facebook.react.bridge.Arguments +import com.facebook.react.bridge.Promise +import com.facebook.react.bridge.ReactApplicationContext +import com.facebook.react.bridge.ReactContextBaseJavaModule +import com.facebook.react.bridge.ReactMethod +import com.facebook.react.bridge.ReadableArray +import org.json.JSONArray +import org.json.JSONObject + +class CactusModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) { + companion object { + private const val DEFAULT_BUFFER_SIZE = 65536 + private const val LARGE_BUFFER_SIZE = 1 shl 20 + private const val DEFAULT_EMBEDDING_BUFFER_SIZE = 4096 + private const val DEFAULT_TOKEN_BUFFER_SIZE = 8192 + private const val DEFAULT_INDEX_RESULT_CAPACITY = 1000 + private const val DEFAULT_INDEX_DOC_BUFFER_SIZE = 4096 + private const val DEFAULT_INDEX_EMBED_BUFFER_SIZE = 4096 + } + + override fun getName(): String = "Cactus" + + private fun parseHandle(handle: String, promise: Promise): Long? { + val parsed = handle.toLongOrNull() + if (parsed == null) { + promise.reject("CACTUS_ERROR", "Invalid native handle") + } + return parsed + } + + private fun fail(promise: Promise, defaultMessage: String) { + val message = CactusJNI.nativeGetLastError().ifEmpty { defaultMessage } + promise.reject("CACTUS_ERROR", message) + } + + private fun decodeNullTerminatedUtf8(buffer: ByteArray): String { + val end = buffer.indexOf(0).let { if (it >= 0) it else buffer.size } + return buffer.copyOf(end).toString(Charsets.UTF_8) + } + + private fun decodeBase64OrNull(value: String?): ByteArray? = + if (value == null) null else Base64.decode(value, Base64.DEFAULT) + + private fun readableArrayToIntArray(values: ReadableArray): IntArray = + IntArray(values.size()) { index -> values.getDouble(index).toInt() } + + private fun readableArrayToFloatArray(values: ReadableArray): FloatArray = + FloatArray(values.size()) { index -> values.getDouble(index).toFloat() } + + private fun readableArrayToStringArray(values: ReadableArray): Array = + Array(values.size()) { index -> values.getString(index) ?: "" } + + private fun readableNestedFloatArrays(values: ReadableArray): Array = + Array(values.size()) { index -> + readableArrayToFloatArray(values.getArray(index) ?: throw IllegalArgumentException("embeddings[$index] is null")) + } + + @ReactMethod + fun init(modelPath: String, corpusDir: String?, cacheIndex: Boolean, promise: Promise) { + val handle = CactusJNI.nativeInit(modelPath, corpusDir, cacheIndex) + if (handle == 0L) { + fail(promise, "Failed to initialize model") + return + } + promise.resolve(handle.toString()) + } + + @ReactMethod + fun destroy(handle: String, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + CactusJNI.nativeDestroy(nativeHandle) + promise.resolve(null) + } + + @ReactMethod + fun reset(handle: String, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + CactusJNI.nativeReset(nativeHandle) + promise.resolve(null) + } + + @ReactMethod + fun stop(handle: String, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + CactusJNI.nativeStop(nativeHandle) + promise.resolve(null) + } + + @ReactMethod + fun prefill( + handle: String, + messagesJson: String, + optionsJson: String?, + toolsJson: String?, + pcmDataBase64: String?, + promise: Promise, + ) { + val buffer = ByteArray(DEFAULT_BUFFER_SIZE) + val nativeHandle = parseHandle(handle, promise) ?: return + val rc = CactusJNI.nativePrefill( + nativeHandle, + messagesJson, + buffer, + optionsJson, + toolsJson, + decodeBase64OrNull(pcmDataBase64), + ) + if (rc < 0) { + fail(promise, "Prefill failed") + return + } + promise.resolve(decodeNullTerminatedUtf8(buffer)) + } + + @ReactMethod + fun complete( + handle: String, + messagesJson: String, + optionsJson: String?, + toolsJson: String?, + pcmDataBase64: String?, + promise: Promise, + ) { + val buffer = ByteArray(DEFAULT_BUFFER_SIZE) + val nativeHandle = parseHandle(handle, promise) ?: return + val rc = CactusJNI.nativeComplete( + nativeHandle, + messagesJson, + buffer, + optionsJson, + toolsJson, + null, + decodeBase64OrNull(pcmDataBase64), + ) + if (rc < 0) { + fail(promise, "Completion failed") + return + } + promise.resolve(decodeNullTerminatedUtf8(buffer)) + } + + @ReactMethod + fun tokenize(handle: String, text: String, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val buffer = IntArray(DEFAULT_TOKEN_BUFFER_SIZE) + val outLen = LongArray(1) + val rc = CactusJNI.nativeTokenize(nativeHandle, text, buffer, outLen) + if (rc < 0) { + fail(promise, "Tokenization failed") + return + } + val result = Arguments.createArray() + for (i in 0 until outLen[0].toInt()) { + result.pushInt(buffer[i]) + } + promise.resolve(result) + } + + @ReactMethod + fun scoreWindow(handle: String, tokens: ReadableArray, start: Double, end: Double, context: Double, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val buffer = ByteArray(DEFAULT_BUFFER_SIZE) + val rc = CactusJNI.nativeScoreWindow( + nativeHandle, + readableArrayToIntArray(tokens), + start.toLong(), + end.toLong(), + context.toLong(), + buffer, + ) + if (rc < 0) { + fail(promise, "Score window failed") + return + } + promise.resolve(decodeNullTerminatedUtf8(buffer)) + } + + @ReactMethod + fun transcribe( + handle: String, + audioPath: String?, + prompt: String?, + optionsJson: String?, + pcmDataBase64: String?, + promise: Promise, + ) { + val buffer = ByteArray(DEFAULT_BUFFER_SIZE) + val nativeHandle = parseHandle(handle, promise) ?: return + val rc = CactusJNI.nativeTranscribe( + nativeHandle, + audioPath, + prompt ?: "", + buffer, + optionsJson, + null, + decodeBase64OrNull(pcmDataBase64), + ) + if (rc < 0) { + fail(promise, "Transcription failed") + return + } + promise.resolve(decodeNullTerminatedUtf8(buffer)) + } + + @ReactMethod + fun embed(handle: String, text: String, normalize: Boolean, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val buffer = FloatArray(DEFAULT_EMBEDDING_BUFFER_SIZE) + val outDim = LongArray(1) + val rc = CactusJNI.nativeEmbed(nativeHandle, text, buffer, outDim, normalize) + if (rc < 0) { + fail(promise, "Embedding failed") + return + } + val result = Arguments.createArray() + for (i in 0 until outDim[0].toInt()) { + result.pushDouble(buffer[i].toDouble()) + } + promise.resolve(result) + } + + @ReactMethod + fun imageEmbed(handle: String, imagePath: String, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val buffer = FloatArray(DEFAULT_EMBEDDING_BUFFER_SIZE) + val outDim = LongArray(1) + val rc = CactusJNI.nativeImageEmbed(nativeHandle, imagePath, buffer, outDim) + if (rc < 0) { + fail(promise, "Image embedding failed") + return + } + val result = Arguments.createArray() + for (i in 0 until outDim[0].toInt()) { + result.pushDouble(buffer[i].toDouble()) + } + promise.resolve(result) + } + + @ReactMethod + fun audioEmbed(handle: String, audioPath: String, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val buffer = FloatArray(DEFAULT_EMBEDDING_BUFFER_SIZE) + val outDim = LongArray(1) + val rc = CactusJNI.nativeAudioEmbed(nativeHandle, audioPath, buffer, outDim) + if (rc < 0) { + fail(promise, "Audio embedding failed") + return + } + val result = Arguments.createArray() + for (i in 0 until outDim[0].toInt()) { + result.pushDouble(buffer[i].toDouble()) + } + promise.resolve(result) + } + + @ReactMethod + fun vad(handle: String, audioPath: String?, optionsJson: String?, pcmDataBase64: String?, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val buffer = ByteArray(DEFAULT_BUFFER_SIZE) + val rc = CactusJNI.nativeVad(nativeHandle, audioPath, buffer, optionsJson, decodeBase64OrNull(pcmDataBase64)) + if (rc < 0) { + fail(promise, "VAD failed") + return + } + promise.resolve(decodeNullTerminatedUtf8(buffer)) + } + + @ReactMethod + fun diarize(handle: String, audioPath: String?, optionsJson: String?, pcmDataBase64: String?, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val buffer = ByteArray(LARGE_BUFFER_SIZE) + val rc = CactusJNI.nativeDiarize(nativeHandle, audioPath, buffer, optionsJson, decodeBase64OrNull(pcmDataBase64)) + if (rc < 0) { + fail(promise, "Diarize failed") + return + } + promise.resolve(decodeNullTerminatedUtf8(buffer)) + } + + @ReactMethod + fun embedSpeaker( + handle: String, + audioPath: String?, + optionsJson: String?, + pcmDataBase64: String?, + maskWeights: ReadableArray?, + promise: Promise, + ) { + val nativeHandle = parseHandle(handle, promise) ?: return + val buffer = ByteArray(DEFAULT_BUFFER_SIZE) + val mask = maskWeights?.let { readableArrayToFloatArray(it) } + val rc = CactusJNI.nativeEmbedSpeaker( + nativeHandle, + audioPath, + buffer, + optionsJson, + decodeBase64OrNull(pcmDataBase64), + mask, + mask?.size?.toLong() ?: 0L, + ) + if (rc < 0) { + fail(promise, "EmbedSpeaker failed") + return + } + promise.resolve(decodeNullTerminatedUtf8(buffer)) + } + + @ReactMethod + fun ragQuery(handle: String, query: String, topK: Double, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val buffer = ByteArray(DEFAULT_BUFFER_SIZE) + val rc = CactusJNI.nativeRagQuery(nativeHandle, query, buffer, topK.toLong()) + if (rc < 0) { + fail(promise, "RAG query failed") + return + } + promise.resolve(decodeNullTerminatedUtf8(buffer)) + } + + @ReactMethod + fun indexInit(indexDir: String, embeddingDim: Double, promise: Promise) { + val handle = CactusJNI.nativeIndexInit(indexDir, embeddingDim.toLong()) + if (handle == 0L) { + fail(promise, "Failed to initialize index") + return + } + promise.resolve(handle.toString()) + } + + @ReactMethod + fun indexAdd( + handle: String, + ids: ReadableArray, + documents: ReadableArray, + embeddings: ReadableArray, + metadatas: ReadableArray?, + promise: Promise, + ) { + val nativeHandle = parseHandle(handle, promise) ?: return + val idsArray = readableArrayToIntArray(ids) + val docsArray = readableArrayToStringArray(documents) + val embArray = readableNestedFloatArrays(embeddings) + val metaArray = metadatas?.let { readableArrayToStringArray(it) } + val embeddingDim = if (embArray.isNotEmpty()) embArray[0].size.toLong() else 0L + val rc = CactusJNI.nativeIndexAdd(nativeHandle, idsArray, docsArray, metaArray, embArray, embeddingDim) + if (rc < 0) { + fail(promise, "Failed to add to index") + return + } + promise.resolve(null) + } + + @ReactMethod + fun indexDelete(handle: String, ids: ReadableArray, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val rc = CactusJNI.nativeIndexDelete(nativeHandle, readableArrayToIntArray(ids)) + if (rc < 0) { + fail(promise, "Failed to delete from index") + return + } + promise.resolve(null) + } + + @ReactMethod + fun indexGet(handle: String, ids: ReadableArray, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val idArray = readableArrayToIntArray(ids) + val count = idArray.size + val docBuffers = Array(count) { ByteArray(DEFAULT_INDEX_DOC_BUFFER_SIZE) } + val docSizes = LongArray(count) { DEFAULT_INDEX_DOC_BUFFER_SIZE.toLong() } + val metaBuffers = Array(count) { ByteArray(DEFAULT_INDEX_DOC_BUFFER_SIZE) } + val metaSizes = LongArray(count) { DEFAULT_INDEX_DOC_BUFFER_SIZE.toLong() } + val embBuffers = Array(count) { FloatArray(DEFAULT_INDEX_EMBED_BUFFER_SIZE) } + val embSizes = LongArray(count) { DEFAULT_INDEX_EMBED_BUFFER_SIZE.toLong() } + val rc = CactusJNI.nativeIndexGet( + nativeHandle, + idArray, + docBuffers, + docSizes, + metaBuffers, + metaSizes, + embBuffers, + embSizes, + ) + if (rc < 0) { + fail(promise, "Failed to get from index") + return + } + val results = JSONArray() + for (i in 0 until count) { + val item = JSONObject() + val document = decodeNullTerminatedUtf8(docBuffers[i]) + val metadataRaw = decodeNullTerminatedUtf8(metaBuffers[i]) + val embDim = embSizes[i].toInt() + val embeddingJson = JSONArray() + for (value in embBuffers[i].copyOf(embDim)) { + embeddingJson.put(value.toDouble()) + } + item.put("document", document) + if (metadataRaw.isEmpty()) { + item.put("metadata", JSONObject.NULL) + } else { + item.put("metadata", metadataRaw) + } + item.put("embedding", embeddingJson) + results.put(item) + } + promise.resolve(JSONObject().put("results", results).toString()) + } + + @ReactMethod + fun indexQuery(handle: String, embedding: ReadableArray, optionsJson: String?, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val emb = readableArrayToFloatArray(embedding) + val idBuffers = arrayOf(IntArray(DEFAULT_INDEX_RESULT_CAPACITY)) + val idSizes = LongArray(1) { DEFAULT_INDEX_RESULT_CAPACITY.toLong() } + val scoreBuffers = arrayOf(FloatArray(DEFAULT_INDEX_RESULT_CAPACITY)) + val scoreSizes = LongArray(1) { DEFAULT_INDEX_RESULT_CAPACITY.toLong() } + val rc = CactusJNI.nativeIndexQuery( + nativeHandle, + arrayOf(emb), + emb.size.toLong(), + optionsJson, + idBuffers, + idSizes, + scoreBuffers, + scoreSizes, + ) + if (rc < 0) { + fail(promise, "Index query failed") + return + } + val results = JSONArray() + for (i in 0 until idSizes[0].toInt()) { + results.put( + JSONObject() + .put("id", idBuffers[0][i]) + .put("score", scoreBuffers[0][i].toDouble()), + ) + } + promise.resolve(JSONObject().put("results", results).toString()) + } + + @ReactMethod + fun indexCompact(handle: String, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + val rc = CactusJNI.nativeIndexCompact(nativeHandle) + if (rc < 0) { + fail(promise, "Failed to compact index") + return + } + promise.resolve(null) + } + + @ReactMethod + fun indexDestroy(handle: String, promise: Promise) { + val nativeHandle = parseHandle(handle, promise) ?: return + CactusJNI.nativeIndexDestroy(nativeHandle) + promise.resolve(null) + } + + @ReactMethod + fun logSetLevel(level: Double, promise: Promise) { + CactusJNI.nativeLogSetLevel(level.toInt()) + promise.resolve(null) + } + + @ReactMethod + fun setTelemetryEnvironment(framework: String?, cacheLocation: String?, version: String?, promise: Promise) { + CactusJNI.nativeSetTelemetryEnvironment(framework, cacheLocation, version) + promise.resolve(null) + } + + @ReactMethod + fun setAppId(appId: String, promise: Promise) { + CactusJNI.nativeSetAppId(appId) + promise.resolve(null) + } + + @ReactMethod + fun telemetryFlush(promise: Promise) { + CactusJNI.nativeTelemetryFlush() + promise.resolve(null) + } + + @ReactMethod + fun telemetryShutdown(promise: Promise) { + CactusJNI.nativeTelemetryShutdown() + promise.resolve(null) + } + + @ReactMethod + fun getLastError(promise: Promise) { + promise.resolve(CactusJNI.nativeGetLastError()) + } +} diff --git a/bindings/react-native/android/CactusPackage.kt b/bindings/react-native/android/CactusPackage.kt new file mode 100644 index 000000000..066db81ab --- /dev/null +++ b/bindings/react-native/android/CactusPackage.kt @@ -0,0 +1,14 @@ +package com.cactus.reactnative + +import com.facebook.react.ReactPackage +import com.facebook.react.bridge.NativeModule +import com.facebook.react.bridge.ReactApplicationContext +import com.facebook.react.uimanager.ViewManager + +class CactusPackage : ReactPackage { + override fun createNativeModules(reactContext: ReactApplicationContext): List = + listOf(CactusModule(reactContext)) + + override fun createViewManagers(reactContext: ReactApplicationContext): List> = + emptyList() +} diff --git a/bindings/react-native/apple/Cactus.m b/bindings/react-native/apple/Cactus.m new file mode 100644 index 000000000..f6f8a61cc --- /dev/null +++ b/bindings/react-native/apple/Cactus.m @@ -0,0 +1,40 @@ +#import + +@interface RCT_EXTERN_MODULE(Cactus, NSObject) + +RCT_EXTERN_METHOD(init:(NSString *)modelPath corpusDir:(NSString * _Nullable)corpusDir cacheIndex:(BOOL)cacheIndex resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(destroy:(NSString *)handle resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(reset:(NSString *)handle resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(stop:(NSString *)handle resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(prefill:(NSString *)handle messagesJson:(NSString *)messagesJson optionsJson:(NSString * _Nullable)optionsJson toolsJson:(NSString * _Nullable)toolsJson pcmDataBase64:(NSString * _Nullable)pcmDataBase64 resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(complete:(NSString *)handle messagesJson:(NSString *)messagesJson optionsJson:(NSString * _Nullable)optionsJson toolsJson:(NSString * _Nullable)toolsJson pcmDataBase64:(NSString * _Nullable)pcmDataBase64 resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(tokenize:(NSString *)handle text:(NSString *)text resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(scoreWindow:(NSString *)handle tokens:(NSArray *)tokens start:(nonnull NSNumber *)start end:(nonnull NSNumber *)end context:(nonnull NSNumber *)context resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(transcribe:(NSString *)handle audioPath:(NSString * _Nullable)audioPath prompt:(NSString * _Nullable)prompt optionsJson:(NSString * _Nullable)optionsJson pcmDataBase64:(NSString * _Nullable)pcmDataBase64 resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(embed:(NSString *)handle text:(NSString *)text normalize:(BOOL)normalize resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(imageEmbed:(NSString *)handle imagePath:(NSString *)imagePath resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(audioEmbed:(NSString *)handle audioPath:(NSString *)audioPath resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(vad:(NSString *)handle audioPath:(NSString * _Nullable)audioPath optionsJson:(NSString * _Nullable)optionsJson pcmDataBase64:(NSString * _Nullable)pcmDataBase64 resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(diarize:(NSString *)handle audioPath:(NSString * _Nullable)audioPath optionsJson:(NSString * _Nullable)optionsJson pcmDataBase64:(NSString * _Nullable)pcmDataBase64 resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(embedSpeaker:(NSString *)handle audioPath:(NSString * _Nullable)audioPath optionsJson:(NSString * _Nullable)optionsJson pcmDataBase64:(NSString * _Nullable)pcmDataBase64 maskWeights:(NSArray * _Nullable)maskWeights resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(ragQuery:(NSString *)handle query:(NSString *)query topK:(nonnull NSNumber *)topK resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(indexInit:(NSString *)indexDir embeddingDim:(nonnull NSNumber *)embeddingDim resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(indexAdd:(NSString *)handle ids:(NSArray *)ids documents:(NSArray *)documents embeddings:(NSArray *> *)embeddings metadatas:(NSArray * _Nullable)metadatas resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(indexDelete:(NSString *)handle ids:(NSArray *)ids resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(indexGet:(NSString *)handle ids:(NSArray *)ids resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(indexQuery:(NSString *)handle embedding:(NSArray *)embedding optionsJson:(NSString * _Nullable)optionsJson resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(indexCompact:(NSString *)handle resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(indexDestroy:(NSString *)handle resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(logSetLevel:(nonnull NSNumber *)level resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(setTelemetryEnvironment:(NSString * _Nullable)framework cacheLocation:(NSString * _Nullable)cacheLocation version:(NSString * _Nullable)version resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(setAppId:(NSString *)appId resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(telemetryFlush:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(telemetryShutdown:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) +RCT_EXTERN_METHOD(getLastError:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) + ++ (BOOL)requiresMainQueueSetup +{ + return NO; +} + +@end diff --git a/bindings/react-native/apple/Cactus.swift b/bindings/react-native/apple/Cactus.swift new file mode 100644 index 000000000..a9732a35c --- /dev/null +++ b/bindings/react-native/apple/Cactus.swift @@ -0,0 +1,626 @@ +import Foundation +import React +import cactus + +@objc(Cactus) +final class Cactus: NSObject { + private let defaultBufferSize = 65_536 + private let largeBufferSize = 1 << 20 + private let defaultEmbeddingBufferSize = 4096 + private let defaultTokenBufferSize = 8192 + private let defaultIndexResultCapacity = 1000 + private let defaultIndexDocBufferSize = 4096 + private let defaultIndexEmbeddingBufferSize = 4096 + + @objc + static func requiresMainQueueSetup() -> Bool { + false + } + + private func lastError(_ fallback: String) -> String { + guard let ptr = cactus_get_last_error() else { return fallback } + return String(cString: ptr) + } + + private func reject(_ rejecter: RCTPromiseRejectBlock, _ fallback: String) { + rejecter("CACTUS_ERROR", lastError(fallback), nil) + } + + private func decodeBase64(_ value: String?) -> Data? { + guard let value else { return nil } + return Data(base64Encoded: value) + } + + private func stringFromBuffer(_ buffer: [CChar]) -> String { + String(cString: buffer) + } + + private func encodeHandle(_ handle: UnsafeMutableRawPointer) -> String { + String(UInt(bitPattern: handle)) + } + + private func decodeHandle(_ handle: String) -> UnsafeMutableRawPointer? { + guard let bits = UInt(handle) else { return nil } + return UnsafeMutableRawPointer(bitPattern: bits) + } + + @objc(init:corpusDir:cacheIndex:resolver:rejecter:) + func initialize(_ modelPath: String, corpusDir: String?, cacheIndex: Bool, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + let handle = cactus_init(modelPath, corpusDir, cacheIndex) + guard let handle else { + self.reject(reject, "Failed to initialize model") + return + } + resolve(encodeHandle(handle)) + } + + @objc(destroy:resolver:rejecter:) + func destroy(_ handle: String, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + cactus_destroy(nativeHandle) + resolve(nil) + } + + @objc(reset:resolver:rejecter:) + func reset(_ handle: String, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + cactus_reset(nativeHandle) + resolve(nil) + } + + @objc(stop:resolver:rejecter:) + func stop(_ handle: String, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + cactus_stop(nativeHandle) + resolve(nil) + } + + @objc(prefill:messagesJson:optionsJson:toolsJson:pcmDataBase64:resolver:rejecter:) + func prefill( + _ handle: String, + messagesJson: String, + optionsJson: String?, + toolsJson: String?, + pcmDataBase64: String?, + resolver resolve: RCTPromiseResolveBlock, + rejecter reject: RCTPromiseRejectBlock + ) { + var buffer = [CChar](repeating: 0, count: defaultBufferSize) + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + let rc = decodeBase64(pcmDataBase64)?.withUnsafeBytes { rawBuffer in + cactus_prefill(nativeHandle, messagesJson, &buffer, buffer.count, optionsJson, toolsJson, rawBuffer.bindMemory(to: UInt8.self).baseAddress, rawBuffer.count) + } ?? cactus_prefill(nativeHandle, messagesJson, &buffer, buffer.count, optionsJson, toolsJson, nil, 0) + guard rc >= 0 else { + self.reject(reject, "Prefill failed") + return + } + resolve(stringFromBuffer(buffer)) + } + + @objc(complete:messagesJson:optionsJson:toolsJson:pcmDataBase64:resolver:rejecter:) + func complete( + _ handle: String, + messagesJson: String, + optionsJson: String?, + toolsJson: String?, + pcmDataBase64: String?, + resolver resolve: RCTPromiseResolveBlock, + rejecter reject: RCTPromiseRejectBlock + ) { + var buffer = [CChar](repeating: 0, count: defaultBufferSize) + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + let rc = decodeBase64(pcmDataBase64)?.withUnsafeBytes { rawBuffer in + cactus_complete(nativeHandle, messagesJson, &buffer, buffer.count, optionsJson, toolsJson, nil, nil, rawBuffer.bindMemory(to: UInt8.self).baseAddress, rawBuffer.count) + } ?? cactus_complete(nativeHandle, messagesJson, &buffer, buffer.count, optionsJson, toolsJson, nil, nil, nil, 0) + guard rc >= 0 else { + self.reject(reject, "Completion failed") + return + } + resolve(stringFromBuffer(buffer)) + } + + @objc(tokenize:text:resolver:rejecter:) + func tokenize(_ handle: String, text: String, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var buffer = [UInt32](repeating: 0, count: defaultTokenBufferSize) + var outLen: Int = 0 + let rc = cactus_tokenize(nativeHandle, text, &buffer, buffer.count, &outLen) + guard rc >= 0 else { + self.reject(reject, "Tokenization failed") + return + } + resolve(buffer.prefix(outLen).map(Int.init)) + } + + @objc(scoreWindow:tokens:start:end:context:resolver:rejecter:) + func scoreWindow( + _ handle: String, + tokens: [NSNumber], + start: NSNumber, + end: NSNumber, + context: NSNumber, + resolver resolve: RCTPromiseResolveBlock, + rejecter reject: RCTPromiseRejectBlock + ) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var tokenValues = tokens.map { UInt32(truncating: $0) } + var buffer = [CChar](repeating: 0, count: defaultBufferSize) + let rc = cactus_score_window(nativeHandle, &tokenValues, tokenValues.count, start.intValue, end.intValue, context.intValue, &buffer, buffer.count) + guard rc >= 0 else { + self.reject(reject, "Score window failed") + return + } + resolve(stringFromBuffer(buffer)) + } + + @objc(transcribe:audioPath:prompt:optionsJson:pcmDataBase64:resolver:rejecter:) + func transcribe( + _ handle: String, + audioPath: String?, + prompt: String?, + optionsJson: String?, + pcmDataBase64: String?, + resolver resolve: RCTPromiseResolveBlock, + rejecter reject: RCTPromiseRejectBlock + ) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var buffer = [CChar](repeating: 0, count: defaultBufferSize) + let promptValue = prompt ?? "" + let rc = decodeBase64(pcmDataBase64)?.withUnsafeBytes { rawBuffer in + cactus_transcribe(nativeHandle, audioPath, promptValue, &buffer, buffer.count, optionsJson, nil, nil, rawBuffer.bindMemory(to: UInt8.self).baseAddress, rawBuffer.count) + } ?? cactus_transcribe(nativeHandle, audioPath, promptValue, &buffer, buffer.count, optionsJson, nil, nil, nil, 0) + guard rc >= 0 else { + self.reject(reject, "Transcription failed") + return + } + resolve(stringFromBuffer(buffer)) + } + + @objc(embed:text:normalize:resolver:rejecter:) + func embed(_ handle: String, text: String, normalize: Bool, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var buffer = [Float](repeating: 0, count: defaultEmbeddingBufferSize) + var dim: Int = 0 + let rc = cactus_embed(nativeHandle, text, &buffer, buffer.count, &dim, normalize) + guard rc >= 0 else { + self.reject(reject, "Embedding failed") + return + } + resolve(buffer.prefix(dim).map(Double.init)) + } + + @objc(imageEmbed:imagePath:resolver:rejecter:) + func imageEmbed(_ handle: String, imagePath: String, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var buffer = [Float](repeating: 0, count: defaultEmbeddingBufferSize) + var dim: Int = 0 + let rc = cactus_image_embed(nativeHandle, imagePath, &buffer, buffer.count, &dim) + guard rc >= 0 else { + self.reject(reject, "Image embedding failed") + return + } + resolve(buffer.prefix(dim).map(Double.init)) + } + + @objc(audioEmbed:audioPath:resolver:rejecter:) + func audioEmbed(_ handle: String, audioPath: String, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var buffer = [Float](repeating: 0, count: defaultEmbeddingBufferSize) + var dim: Int = 0 + let rc = cactus_audio_embed(nativeHandle, audioPath, &buffer, buffer.count, &dim) + guard rc >= 0 else { + self.reject(reject, "Audio embedding failed") + return + } + resolve(buffer.prefix(dim).map(Double.init)) + } + + @objc(vad:audioPath:optionsJson:pcmDataBase64:resolver:rejecter:) + func vad( + _ handle: String, + audioPath: String?, + optionsJson: String?, + pcmDataBase64: String?, + resolver resolve: RCTPromiseResolveBlock, + rejecter reject: RCTPromiseRejectBlock + ) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var buffer = [CChar](repeating: 0, count: defaultBufferSize) + let rc = decodeBase64(pcmDataBase64)?.withUnsafeBytes { rawBuffer in + cactus_vad(nativeHandle, audioPath, &buffer, buffer.count, optionsJson, rawBuffer.bindMemory(to: UInt8.self).baseAddress, rawBuffer.count) + } ?? cactus_vad(nativeHandle, audioPath, &buffer, buffer.count, optionsJson, nil, 0) + guard rc >= 0 else { + self.reject(reject, "VAD failed") + return + } + resolve(stringFromBuffer(buffer)) + } + + @objc(diarize:audioPath:optionsJson:pcmDataBase64:resolver:rejecter:) + func diarize( + _ handle: String, + audioPath: String?, + optionsJson: String?, + pcmDataBase64: String?, + resolver resolve: RCTPromiseResolveBlock, + rejecter reject: RCTPromiseRejectBlock + ) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var buffer = [CChar](repeating: 0, count: largeBufferSize) + let rc = decodeBase64(pcmDataBase64)?.withUnsafeBytes { rawBuffer in + cactus_diarize(nativeHandle, audioPath, &buffer, buffer.count, optionsJson, rawBuffer.bindMemory(to: UInt8.self).baseAddress, rawBuffer.count) + } ?? cactus_diarize(nativeHandle, audioPath, &buffer, buffer.count, optionsJson, nil, 0) + guard rc >= 0 else { + self.reject(reject, "Diarize failed") + return + } + resolve(stringFromBuffer(buffer)) + } + + @objc(embedSpeaker:audioPath:optionsJson:pcmDataBase64:maskWeights:resolver:rejecter:) + func embedSpeaker( + _ handle: String, + audioPath: String?, + optionsJson: String?, + pcmDataBase64: String?, + maskWeights: [NSNumber]?, + resolver resolve: RCTPromiseResolveBlock, + rejecter reject: RCTPromiseRejectBlock + ) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var buffer = [CChar](repeating: 0, count: defaultBufferSize) + var mask = maskWeights?.map { Float(truncating: $0) } + let rc = decodeBase64(pcmDataBase64)?.withUnsafeBytes { rawBuffer in + if var mask { + return cactus_embed_speaker(nativeHandle, audioPath, &buffer, buffer.count, optionsJson, rawBuffer.bindMemory(to: UInt8.self).baseAddress, rawBuffer.count, &mask, mask.count) + } + return cactus_embed_speaker(nativeHandle, audioPath, &buffer, buffer.count, optionsJson, rawBuffer.bindMemory(to: UInt8.self).baseAddress, rawBuffer.count, nil, 0) + } ?? { + if var mask { + return cactus_embed_speaker(nativeHandle, audioPath, &buffer, buffer.count, optionsJson, nil, 0, &mask, mask.count) + } + return cactus_embed_speaker(nativeHandle, audioPath, &buffer, buffer.count, optionsJson, nil, 0, nil, 0) + }() + guard rc >= 0 else { + self.reject(reject, "EmbedSpeaker failed") + return + } + resolve(stringFromBuffer(buffer)) + } + + @objc(ragQuery:query:topK:resolver:rejecter:) + func ragQuery(_ handle: String, query: String, topK: NSNumber, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var buffer = [CChar](repeating: 0, count: defaultBufferSize) + let rc = cactus_rag_query(nativeHandle, query, &buffer, buffer.count, topK.intValue) + guard rc >= 0 else { + self.reject(reject, "RAG query failed") + return + } + resolve(stringFromBuffer(buffer)) + } + + @objc(indexInit:embeddingDim:resolver:rejecter:) + func indexInit(_ indexDir: String, embeddingDim: NSNumber, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + let handle = cactus_index_init(indexDir, embeddingDim.intValue) + guard let handle else { + self.reject(reject, "Failed to initialize index") + return + } + resolve(encodeHandle(handle)) + } + + @objc(indexAdd:ids:documents:embeddings:metadatas:resolver:rejecter:) + func indexAdd( + _ handle: String, + ids: [NSNumber], + documents: [String], + embeddings: [[NSNumber]], + metadatas: [String]?, + resolver resolve: RCTPromiseResolveBlock, + rejecter reject: RCTPromiseRejectBlock + ) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var idValues = ids.map { Int32(truncating: $0) } + var docStrings = documents.map { strdup($0) } + var docPointers = docStrings.map { UnsafePointer($0) } + var metaStrings = metadatas?.map { strdup($0) } + var metaPointers = metaStrings?.map { UnsafePointer($0) } + let embeddingDim = embeddings.first?.count ?? 0 + var embeddingPointers = embeddings.map { row -> UnsafeMutablePointer in + let ptr = UnsafeMutablePointer.allocate(capacity: row.count) + for (index, value) in row.enumerated() { + ptr[index] = Float(truncating: value) + } + return ptr + } + var embeddingConstPointers: [UnsafePointer?] = embeddingPointers.map { UnsafePointer($0) } + defer { + docStrings.forEach { free($0) } + metaStrings?.forEach { free($0) } + embeddingPointers.forEach { $0.deallocate() } + } + var idsCopy = idValues + let rc = idsCopy.withUnsafeMutableBufferPointer { idBuffer in + docPointers.withUnsafeMutableBufferPointer { docBuffer in + embeddingConstPointers.withUnsafeMutableBufferPointer { embBuffer in + if var metaPointers { + return metaPointers.withUnsafeMutableBufferPointer { metaBuffer in + cactus_index_add( + nativeHandle, + idBuffer.baseAddress, + docBuffer.baseAddress, + metaBuffer.baseAddress, + embBuffer.baseAddress, + idValues.count, + embeddingDim + ) + } + } + return cactus_index_add( + nativeHandle, + idBuffer.baseAddress, + docBuffer.baseAddress, + nil, + embBuffer.baseAddress, + idValues.count, + embeddingDim + ) + } + } + } + guard rc >= 0 else { + self.reject(reject, "Failed to add to index") + return + } + resolve(nil) + } + + @objc(indexDelete:ids:resolver:rejecter:) + func indexDelete(_ handle: String, ids: [NSNumber], resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var idValues = ids.map { Int32(truncating: $0) } + let rc = cactus_index_delete(nativeHandle, &idValues, idValues.count) + guard rc >= 0 else { + self.reject(reject, "Failed to delete from index") + return + } + resolve(nil) + } + + @objc(indexGet:ids:resolver:rejecter:) + func indexGet(_ handle: String, ids: [NSNumber], resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + var idValues = ids.map { Int32(truncating: $0) } + let count = idValues.count + var docPointers: [UnsafeMutablePointer?] = (0...allocate(capacity: defaultIndexDocBufferSize) } + var docSizes = Array(repeating: defaultIndexDocBufferSize, count: count) + var metaPointers: [UnsafeMutablePointer?] = (0...allocate(capacity: defaultIndexDocBufferSize) } + var metaSizes = Array(repeating: defaultIndexDocBufferSize, count: count) + var embPointers: [UnsafeMutablePointer?] = (0...allocate(capacity: defaultIndexEmbeddingBufferSize) } + var embSizes = Array(repeating: defaultIndexEmbeddingBufferSize, count: count) + defer { + docPointers.forEach { $0?.deallocate() } + metaPointers.forEach { $0?.deallocate() } + embPointers.forEach { $0?.deallocate() } + } + for i in 0..= 0 else { + self.reject(reject, "Failed to get from index") + return + } + var results = [[String: Any]]() + for i in 0..? = UnsafePointer(embBuffer.baseAddress) + return idStorage.withUnsafeMutableBufferPointer { idBuffer in + var idPointer: UnsafeMutablePointer? = idBuffer.baseAddress + return scoreStorage.withUnsafeMutableBufferPointer { scoreBuffer in + var scorePointer: UnsafeMutablePointer? = scoreBuffer.baseAddress + return cactus_index_query( + nativeHandle, + &embPointer, + 1, + embValues.count, + optionsJson, + &idPointer, + &idSizes, + &scorePointer, + &scoreSizes + ) + } + } + } + guard rc >= 0 else { + self.reject(reject, "Index query failed") + return + } + let results = (0..= 0 else { + self.reject(reject, "Failed to compact index") + return + } + resolve(nil) + } + + @objc(indexDestroy:resolver:rejecter:) + func indexDestroy(_ handle: String, resolver resolve: RCTPromiseResolveBlock, rejecter reject: RCTPromiseRejectBlock) { + guard let nativeHandle = decodeHandle(handle) else { + self.reject(reject, "Invalid native handle") + return + } + cactus_index_destroy(nativeHandle) + resolve(nil) + } + + @objc(logSetLevel:resolver:rejecter:) + func logSetLevel(_ level: NSNumber, resolver resolve: RCTPromiseResolveBlock, rejecter _: RCTPromiseRejectBlock) { + cactus_log_set_level(level.int32Value) + resolve(nil) + } + + @objc(setTelemetryEnvironment:cacheLocation:version:resolver:rejecter:) + func setTelemetryEnvironment( + _ framework: String?, + cacheLocation: String?, + version: String?, + resolver resolve: RCTPromiseResolveBlock, + rejecter _: RCTPromiseRejectBlock + ) { + cactus_set_telemetry_environment(framework, cacheLocation, version) + resolve(nil) + } + + @objc(setAppId:resolver:rejecter:) + func setAppId(_ appId: String, resolver resolve: RCTPromiseResolveBlock, rejecter _: RCTPromiseRejectBlock) { + cactus_set_app_id(appId) + resolve(nil) + } + + @objc(telemetryFlush:rejecter:) + func telemetryFlush(_ resolve: RCTPromiseResolveBlock, rejecter _: RCTPromiseRejectBlock) { + cactus_telemetry_flush() + resolve(nil) + } + + @objc(telemetryShutdown:rejecter:) + func telemetryShutdown(_ resolve: RCTPromiseResolveBlock, rejecter _: RCTPromiseRejectBlock) { + cactus_telemetry_shutdown() + resolve(nil) + } + + @objc(getLastError:rejecter:) + func getLastError(_ resolve: RCTPromiseResolveBlock, rejecter _: RCTPromiseRejectBlock) { + guard let ptr = cactus_get_last_error() else { + resolve(nil) + return + } + resolve(String(cString: ptr)) + } +} diff --git a/bindings/react-native/index.ts b/bindings/react-native/index.ts new file mode 100644 index 000000000..96b3a0e7c --- /dev/null +++ b/bindings/react-native/index.ts @@ -0,0 +1,97 @@ +import {NativeModules} from 'react-native'; + +export interface CactusNativeModule { + init(modelPath: string, corpusDir: string | null, cacheIndex: boolean): Promise; + destroy(handle: string): Promise; + reset(handle: string): Promise; + stop(handle: string): Promise; + prefill( + handle: string, + messagesJson: string, + optionsJson: string | null, + toolsJson: string | null, + pcmDataBase64: string | null, + ): Promise; + complete( + handle: string, + messagesJson: string, + optionsJson: string | null, + toolsJson: string | null, + pcmDataBase64: string | null, + ): Promise; + tokenize(handle: string, text: string): Promise; + scoreWindow( + handle: string, + tokens: number[], + start: number, + end: number, + context: number, + ): Promise; + transcribe( + handle: string, + audioPath: string | null, + prompt: string | null, + optionsJson: string | null, + pcmDataBase64: string | null, + ): Promise; + embed(handle: string, text: string, normalize: boolean): Promise; + imageEmbed(handle: string, imagePath: string): Promise; + audioEmbed(handle: string, audioPath: string): Promise; + vad( + handle: string, + audioPath: string | null, + optionsJson: string | null, + pcmDataBase64: string | null, + ): Promise; + diarize( + handle: string, + audioPath: string | null, + optionsJson: string | null, + pcmDataBase64: string | null, + ): Promise; + embedSpeaker( + handle: string, + audioPath: string | null, + optionsJson: string | null, + pcmDataBase64: string | null, + maskWeights: number[] | null, + ): Promise; + ragQuery(handle: string, query: string, topK: number): Promise; + indexInit(indexDir: string, embeddingDim: number): Promise; + indexAdd( + handle: string, + ids: number[], + documents: string[], + embeddings: number[][], + metadatas: string[] | null, + ): Promise; + indexDelete(handle: string, ids: number[]): Promise; + indexGet(handle: string, ids: number[]): Promise; + indexQuery(handle: string, embedding: number[], optionsJson: string | null): Promise; + indexCompact(handle: string): Promise; + indexDestroy(handle: string): Promise; + logSetLevel(level: number): Promise; + setTelemetryEnvironment( + framework: string | null, + cacheLocation: string | null, + version: string | null, + ): Promise; + setAppId(appId: string): Promise; + telemetryFlush(): Promise; + telemetryShutdown(): Promise; + getLastError(): Promise; +} + +const LINKING_ERROR = + 'Cactus native module not linked. ' + + 'Add the bindings/react-native native bridge files and register NativeModules.Cactus.'; + +const nativeModule = NativeModules.Cactus as CactusNativeModule | undefined; + +if (!nativeModule) { + throw new Error(LINKING_ERROR); +} + +export const Cactus = nativeModule; + +export default Cactus; diff --git a/bindings/rust/README.md b/bindings/rust/README.md new file mode 100644 index 000000000..8f7029e6b --- /dev/null +++ b/bindings/rust/README.md @@ -0,0 +1,34 @@ +# Rust Bindings + +Raw `extern "C"` declarations for `cactus_engine.h`. + +## Integration + +```bash +cactus build +``` + +1. Copy `cactus.rs` into your project +2. Link against `libcactus.a` in your `build.rs`: + +```rust +println!("cargo:rustc-link-lib=static=cactus"); +println!("cargo:rustc-link-search=native=/path/to/cactus/cactus/build"); +``` + +## Usage + +```rust +use std::ffi::CString; +use std::os::raw::c_char; + +mod cactus; + +unsafe { + let path = CString::new("/path/to/model").unwrap(); + let model = cactus::cactus_init(path.as_ptr(), std::ptr::null(), false); + let mut buf = vec![0i8; 65536]; + cactus::cactus_complete(model, msgs.as_ptr(), buf.as_mut_ptr() as *mut c_char, buf.len(), std::ptr::null(), std::ptr::null(), None, std::ptr::null_mut(), std::ptr::null(), 0); + cactus::cactus_destroy(model); +} +``` diff --git a/bindings/rust/cactus.rs b/bindings/rust/cactus.rs new file mode 100644 index 000000000..5b10d7c57 --- /dev/null +++ b/bindings/rust/cactus.rs @@ -0,0 +1,44 @@ +use std::os::raw::{c_char, c_float, c_int, c_void}; + +pub type CactusModelT = *mut c_void; +pub type CactusIndexT = *mut c_void; +pub type CactusTokenCallback = Option; +pub type CactusLogCallback = Option; + +extern "C" { + pub fn cactus_init(model_path: *const c_char, corpus_dir: *const c_char, cache_index: bool) -> CactusModelT; + pub fn cactus_destroy(model: CactusModelT); + pub fn cactus_reset(model: CactusModelT); + pub fn cactus_stop(model: CactusModelT); + + pub fn cactus_complete(model: CactusModelT, messages_json: *const c_char, response_buffer: *mut c_char, buffer_size: usize, options_json: *const c_char, tools_json: *const c_char, callback: CactusTokenCallback, user_data: *mut c_void, pcm_buffer: *const u8, pcm_buffer_size: usize) -> c_int; + pub fn cactus_prefill(model: CactusModelT, messages_json: *const c_char, response_buffer: *mut c_char, buffer_size: usize, options_json: *const c_char, tools_json: *const c_char, pcm_buffer: *const u8, pcm_buffer_size: usize) -> c_int; + pub fn cactus_tokenize(model: CactusModelT, text: *const c_char, token_buffer: *mut u32, token_buffer_len: usize, out_token_len: *mut usize) -> c_int; + pub fn cactus_score_window(model: CactusModelT, tokens: *const u32, token_len: usize, start: usize, end: usize, context: usize, response_buffer: *mut c_char, buffer_size: usize) -> c_int; + pub fn cactus_transcribe(model: CactusModelT, audio_file_path: *const c_char, prompt: *const c_char, response_buffer: *mut c_char, buffer_size: usize, options_json: *const c_char, callback: CactusTokenCallback, user_data: *mut c_void, pcm_buffer: *const u8, pcm_buffer_size: usize) -> c_int; + + pub fn cactus_embed(model: CactusModelT, text: *const c_char, embeddings_buffer: *mut c_float, buffer_size: usize, embedding_dim: *mut usize, normalize: bool) -> c_int; + pub fn cactus_image_embed(model: CactusModelT, image_path: *const c_char, embeddings_buffer: *mut c_float, buffer_size: usize, embedding_dim: *mut usize) -> c_int; + pub fn cactus_audio_embed(model: CactusModelT, audio_path: *const c_char, embeddings_buffer: *mut c_float, buffer_size: usize, embedding_dim: *mut usize) -> c_int; + + pub fn cactus_vad(model: CactusModelT, audio_file_path: *const c_char, response_buffer: *mut c_char, buffer_size: usize, options_json: *const c_char, pcm_buffer: *const u8, pcm_buffer_size: usize) -> c_int; + pub fn cactus_diarize(model: CactusModelT, audio_file_path: *const c_char, response_buffer: *mut c_char, buffer_size: usize, options_json: *const c_char, pcm_buffer: *const u8, pcm_buffer_size: usize) -> c_int; + pub fn cactus_embed_speaker(model: CactusModelT, audio_file_path: *const c_char, response_buffer: *mut c_char, buffer_size: usize, options_json: *const c_char, pcm_buffer: *const u8, pcm_buffer_size: usize, mask_weights: *const c_float, mask_num_frames: usize) -> c_int; + pub fn cactus_rag_query(model: CactusModelT, query: *const c_char, response_buffer: *mut c_char, buffer_size: usize, top_k: usize) -> c_int; + + pub fn cactus_index_init(index_dir: *const c_char, embedding_dim: usize) -> CactusIndexT; + pub fn cactus_index_add(index: CactusIndexT, ids: *const c_int, documents: *const *const c_char, metadatas: *const *const c_char, embeddings: *const *const c_float, count: usize, embedding_dim: usize) -> c_int; + pub fn cactus_index_delete(index: CactusIndexT, ids: *const c_int, ids_count: usize) -> c_int; + pub fn cactus_index_get(index: CactusIndexT, ids: *const c_int, ids_count: usize, document_buffers: *mut *mut c_char, document_buffer_sizes: *mut usize, metadata_buffers: *mut *mut c_char, metadata_buffer_sizes: *mut usize, embedding_buffers: *mut *mut c_float, embedding_buffer_sizes: *mut usize) -> c_int; + pub fn cactus_index_query(index: CactusIndexT, embeddings: *const *const c_float, embeddings_count: usize, embedding_dim: usize, options_json: *const c_char, id_buffers: *mut *mut c_int, id_buffer_sizes: *mut usize, score_buffers: *mut *mut c_float, score_buffer_sizes: *mut usize) -> c_int; + pub fn cactus_index_compact(index: CactusIndexT) -> c_int; + pub fn cactus_index_destroy(index: CactusIndexT); + + pub fn cactus_get_last_error() -> *const c_char; + pub fn cactus_log_set_level(level: c_int); + pub fn cactus_log_set_callback(callback: CactusLogCallback, user_data: *mut c_void); + pub fn cactus_set_telemetry_environment(framework: *const c_char, cache_location: *const c_char, version: *const c_char); + pub fn cactus_set_app_id(app_id: *const c_char); + pub fn cactus_telemetry_flush(); + pub fn cactus_telemetry_shutdown(); +} diff --git a/bindings/swift/Cactus.swift b/bindings/swift/Cactus.swift new file mode 100644 index 000000000..44a4cbfe7 --- /dev/null +++ b/bindings/swift/Cactus.swift @@ -0,0 +1 @@ +@_exported import cactus diff --git a/bindings/swift/README.md b/bindings/swift/README.md new file mode 100644 index 000000000..d84ab88d5 --- /dev/null +++ b/bindings/swift/README.md @@ -0,0 +1,25 @@ +# Swift Bindings + +C module map import of `cactus_engine.h`. Works on iOS and macOS. + +## Integration + +```bash +cactus build --apple +``` + +**XCFramework**: drag `apple/cactus-ios.xcframework` into Xcode (Embed & Sign). + +**Static library**: add `apple/libcactus-device.a` to Link Binary With Libraries, copy `module.modulemap` and `cactus_engine.h` into Header Search Paths. + +## Usage + +```swift +import cactus + +let model = cactus_init("/path/to/model", nil, false) +var buf = [CChar](repeating: 0, count: 65536) +cactus_complete(model, messagesJson, &buf, buf.count, nil, nil, nil, nil, nil, 0) +let response = String(cString: buf) +cactus_destroy(model) +``` diff --git a/bindings/swift/ffi/cactus_ffi_shim.h b/bindings/swift/ffi/cactus_ffi_shim.h new file mode 100644 index 000000000..ae623eeb8 --- /dev/null +++ b/bindings/swift/ffi/cactus_ffi_shim.h @@ -0,0 +1 @@ +#include "../../../cactus-engine/cactus_engine.h" diff --git a/bindings/swift/ffi/module.modulemap b/bindings/swift/ffi/module.modulemap new file mode 100644 index 000000000..0fc94f2dd --- /dev/null +++ b/bindings/swift/ffi/module.modulemap @@ -0,0 +1,4 @@ +module cactus [system] { + header "cactus_ffi_shim.h" + export * +} diff --git a/apple/module.android.modulemap b/bindings/swift/module.modulemap similarity index 51% rename from apple/module.android.modulemap rename to bindings/swift/module.modulemap index b68f641c2..af75a51b2 100644 --- a/apple/module.android.modulemap +++ b/bindings/swift/module.modulemap @@ -1,4 +1,4 @@ module cactus { - header "cactus_ffi.h" + header "cactus_engine.h" export * } diff --git a/cactus-engine/CMakeLists.txt b/cactus-engine/CMakeLists.txt index 108ea8ed5..b683acf66 100644 --- a/cactus-engine/CMakeLists.txt +++ b/cactus-engine/CMakeLists.txt @@ -37,15 +37,32 @@ endif() # --- libcurl --- set(CACTUS_CURL_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/libs/curl" CACHE PATH "Path to vendored libcurl") +set(CACTUS_CURL_INCLUDE_DIR "${CACTUS_CURL_ROOT}/include") if(APPLE) - set(CACTUS_CURL_INCLUDE_DIR "${CACTUS_CURL_ROOT}/include") - set(CACTUS_CURL_LIBRARY_MACOS "${CACTUS_CURL_ROOT}/macos/libcurl.a") - if(EXISTS "${CACTUS_CURL_INCLUDE_DIR}/curl/curl.h" AND EXISTS "${CACTUS_CURL_LIBRARY_MACOS}") + if(CMAKE_SYSTEM_NAME STREQUAL "iOS") + string(TOLOWER "${CMAKE_OSX_SYSROOT}" _sysroot_lower) + if(_sysroot_lower MATCHES "simulator") + set(CACTUS_CURL_LIBRARY "${CACTUS_CURL_ROOT}/ios/simulator/libcurl.a") + else() + set(CACTUS_CURL_LIBRARY "${CACTUS_CURL_ROOT}/ios/device/libcurl.a") + endif() + else() + set(CACTUS_CURL_LIBRARY "${CACTUS_CURL_ROOT}/macos/libcurl.a") + endif() + if(EXISTS "${CACTUS_CURL_INCLUDE_DIR}/curl/curl.h" AND EXISTS "${CACTUS_CURL_LIBRARY}") set(CACTUS_HAS_CURL TRUE) else() set(CACTUS_HAS_CURL FALSE) message(WARNING "Vendored libcurl not found at ${CACTUS_CURL_ROOT}; cloud features disabled") endif() +elseif(ANDROID) + set(CACTUS_CURL_LIBRARY "${CACTUS_CURL_ROOT}/android/${ANDROID_ABI}/libcurl.a") + if(EXISTS "${CACTUS_CURL_INCLUDE_DIR}/curl/curl.h" AND EXISTS "${CACTUS_CURL_LIBRARY}") + set(CACTUS_HAS_CURL TRUE) + else() + set(CACTUS_HAS_CURL FALSE) + message(WARNING "Vendored libcurl not found for Android; cloud features disabled") + endif() else() find_package(CURL QUIET) set(CACTUS_HAS_CURL ${CURL_FOUND}) @@ -72,14 +89,12 @@ set(ENGINE_SOURCES src/transcribe.cpp src/tokenizer.cpp ) -if(NOT APPLE) - list(APPEND ENGINE_SOURCES src/npu.cpp) -endif() - if(APPLE) enable_language(OBJCXX) list(APPEND ENGINE_SOURCES src/npu_ane.mm) set_source_files_properties(src/npu_ane.mm PROPERTIES COMPILE_FLAGS "-fobjc-arc") +else() + list(APPEND ENGINE_SOURCES src/npu.cpp) endif() add_library(cactus_engine STATIC ${ENGINE_SOURCES}) @@ -96,9 +111,9 @@ set_target_properties(cactus_engine PROPERTIES POSITION_INDEPENDENT_CODE ON) # curl if(CACTUS_HAS_CURL) - if(APPLE) - target_link_libraries(cactus_engine PUBLIC ${CACTUS_CURL_LIBRARY_MACOS}) - target_include_directories(cactus_engine PUBLIC ${CACTUS_CURL_INCLUDE_DIR}) + if(APPLE OR ANDROID) + target_link_libraries(cactus_engine PUBLIC "${CACTUS_CURL_LIBRARY}") + target_include_directories(cactus_engine PUBLIC "${CACTUS_CURL_INCLUDE_DIR}") else() target_link_libraries(cactus_engine PUBLIC ${CURL_LIBRARIES}) target_include_directories(cactus_engine PRIVATE ${CURL_INCLUDE_DIRS}) diff --git a/cactus-engine/test.sh b/cactus-engine/test.sh index a057a280d..50954e0e6 100755 --- a/cactus-engine/test.sh +++ b/cactus-engine/test.sh @@ -4,9 +4,51 @@ set -e cd "$(dirname "$0")" PROJECT_ROOT="$(pwd)/.." -MODEL_DIR="${CACTUS_TEST_MODEL:-$PROJECT_ROOT/weights/gemma-4-e2b-it}" ASSETS_DIR="$(pwd)/tests/assets" +IOS_MODE=false +ANDROID_MODE=false +ONLY_EXEC="" +MODEL_ARG="" + +while [[ $# -gt 0 ]]; do + case $1 in + --ios) + IOS_MODE=true + shift + ;; + --android) + ANDROID_MODE=true + shift + ;; + --only) + [ -z "${2:-}" ] && echo "Error: --only requires an argument" && exit 1 + ONLY_EXEC="$2" + shift 2 + ;; + --model) + [ -z "${2:-}" ] && echo "Error: --model requires an argument" && exit 1 + MODEL_ARG="$2" + shift 2 + ;; + *) + shift + ;; + esac +done + +MODEL_DIR="${CACTUS_TEST_MODEL:-${MODEL_ARG:-$PROJECT_ROOT/weights/gemma-4-e2b-it}}" + +if [ "$IOS_MODE" = true ]; then + export CACTUS_TEST_ONLY="$ONLY_EXEC" + exec "$(pwd)/tests/ios/run.sh" "$MODEL_DIR" +fi + +if [ "$ANDROID_MODE" = true ]; then + export CACTUS_TEST_ONLY="$ONLY_EXEC" + exec "$(pwd)/tests/android/run.sh" "$MODEL_DIR" +fi + if [ ! -d "$MODEL_DIR" ]; then echo "Model weights not found at $MODEL_DIR" echo "Set CACTUS_TEST_MODEL or download weights first." @@ -16,7 +58,6 @@ fi echo "Building and testing cactus-engine..." echo "Model: $MODEL_DIR" -# Build the library cd "$PROJECT_ROOT/cactus" rm -rf build mkdir -p build @@ -24,7 +65,6 @@ cd build cmake .. -DCMAKE_RULE_MESSAGES=OFF -DCMAKE_VERBOSE_MAKEFILE=OFF > /dev/null 2>&1 make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4) -# Build tests cd "$PROJECT_ROOT/cactus-engine/tests" rm -rf build mkdir -p build @@ -38,8 +78,19 @@ export CACTUS_TEST_ASSETS="$ASSETS_DIR" export CACTUS_INDEX_PATH="$ASSETS_DIR" FAILED=0 -for test_bin in test_*; do - [ -x "$test_bin" ] && ./"$test_bin" || FAILED=1 -done + +if [ -n "$ONLY_EXEC" ]; then + target="./test_$ONLY_EXEC" + if [ -x "$target" ]; then + ./"$target" || FAILED=1 + else + echo "Test not found: $target" + FAILED=1 + fi +else + for test_bin in test_*; do + [ -x "$test_bin" ] && ./"$test_bin" || FAILED=1 + done +fi exit $FAILED diff --git a/cactus-engine/tests/android/CMakeLists.txt b/cactus-engine/tests/android/CMakeLists.txt new file mode 100644 index 000000000..02fa18c87 --- /dev/null +++ b/cactus-engine/tests/android/CMakeLists.txt @@ -0,0 +1,81 @@ +cmake_minimum_required(VERSION 3.10) +project(CactusAndroidTests LANGUAGES CXX) + +set(CMAKE_CXX_STANDARD 20) +set(CMAKE_CXX_STANDARD_REQUIRED True) +set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pthread -Wall -Wextra -pedantic -O3") + +set(PROJECT_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/../../..) +set(CACTUS_ENGINE_DIR ${PROJECT_ROOT}/cactus-engine) +set(CACTUS_GRAPH_DIR ${PROJECT_ROOT}/cactus-graph) +set(CACTUS_KERNELS_DIR ${PROJECT_ROOT}/cactus-kernels) + +set(ANDROID_BUILD_DIR ${PROJECT_ROOT}/android/build) +set(CACTUS_LIB ${ANDROID_BUILD_DIR}/lib/libcactus_static.a) + +set(CACTUS_CURL_ROOT "$ENV{CACTUS_CURL_ROOT}") +if(NOT CACTUS_CURL_ROOT) + set(CACTUS_CURL_ROOT ${CACTUS_ENGINE_DIR}/libs/curl) +endif() +set(CACTUS_CURL_INCLUDE_DIR "${CACTUS_CURL_ROOT}/include") +set(CACTUS_CURL_LIBRARY "${CACTUS_CURL_ROOT}/android/arm64-v8a/libcurl.a") + +set(CACTUS_MBEDTLS_ROOT ${PROJECT_ROOT}/android/mbedtls/arm64-v8a) +if(NOT EXISTS "${CACTUS_MBEDTLS_ROOT}") + set(CACTUS_MBEDTLS_ROOT ${PROJECT_ROOT}/libs/mbedtls/android/arm64-v8a) +endif() +set(CACTUS_MBEDTLS_CRYPTO_LIBRARY "${CACTUS_MBEDTLS_ROOT}/lib/libmbedcrypto.a") +set(CACTUS_MBEDTLS_TLS_LIBRARY "${CACTUS_MBEDTLS_ROOT}/lib/libmbedtls.a") +set(CACTUS_MBEDTLS_X509_LIBRARY "${CACTUS_MBEDTLS_ROOT}/lib/libmbedx509.a") + +if(NOT EXISTS ${CACTUS_LIB}) + message(FATAL_ERROR "Cactus library not found at: ${CACTUS_LIB}") +endif() + +message(STATUS "Using Cactus library: ${CACTUS_LIB}") +message(STATUS "Using vendored curl root: ${CACTUS_CURL_ROOT}") + +set(TESTS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/..) +file(GLOB TEST_SOURCES "${TESTS_DIR}/test_*.cpp") +list(REMOVE_ITEM TEST_SOURCES "${TESTS_DIR}/test_utils.cpp") + +function(link_vendored_curl_if_present target_name) + if(CACTUS_CURL_ROOT AND EXISTS "${CACTUS_CURL_INCLUDE_DIR}/curl/curl.h" AND EXISTS "${CACTUS_CURL_LIBRARY}") + if(NOT EXISTS "${CACTUS_MBEDTLS_CRYPTO_LIBRARY}" OR + NOT EXISTS "${CACTUS_MBEDTLS_TLS_LIBRARY}" OR + NOT EXISTS "${CACTUS_MBEDTLS_X509_LIBRARY}") + message(FATAL_ERROR + "Vendored Android libcurl is present but mbedTLS static libs are missing.\n" + "Expected:\n" + " ${CACTUS_MBEDTLS_CRYPTO_LIBRARY}\n" + " ${CACTUS_MBEDTLS_TLS_LIBRARY}\n" + " ${CACTUS_MBEDTLS_X509_LIBRARY}") + endif() + target_include_directories(${target_name} PRIVATE "${CACTUS_CURL_INCLUDE_DIR}") + target_link_libraries(${target_name} PRIVATE + "${CACTUS_CURL_LIBRARY}" + "${CACTUS_MBEDTLS_TLS_LIBRARY}" + "${CACTUS_MBEDTLS_X509_LIBRARY}" + "${CACTUS_MBEDTLS_CRYPTO_LIBRARY}" + ) + message(STATUS "Target ${target_name} will link vendored libcurl: ${CACTUS_CURL_LIBRARY}") + endif() +endfunction() + +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}) + +foreach(TEST_FILE ${TEST_SOURCES}) + get_filename_component(TEST_NAME ${TEST_FILE} NAME_WE) + add_executable(${TEST_NAME} + ${TEST_FILE} + ${TESTS_DIR}/test_utils.cpp + ) + target_link_libraries(${TEST_NAME} PRIVATE ${CACTUS_LIB}) + link_vendored_curl_if_present(${TEST_NAME}) + target_include_directories(${TEST_NAME} PRIVATE + ${CACTUS_ENGINE_DIR} + ${CACTUS_GRAPH_DIR} + ${CACTUS_KERNELS_DIR} + ) + message(STATUS "Added Android test: ${TEST_NAME}") +endforeach() diff --git a/cactus-engine/tests/android/run.sh b/cactus-engine/tests/android/run.sh new file mode 100755 index 000000000..33a0aff50 --- /dev/null +++ b/cactus-engine/tests/android/run.sh @@ -0,0 +1,331 @@ +#!/bin/bash + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)" +CACTUS_CURL_ROOT="${CACTUS_CURL_ROOT:-$PROJECT_ROOT/cactus-engine/libs/curl}" +export CACTUS_CURL_ROOT + +MODEL_NAME="$1" + +if [ -z "$MODEL_NAME" ]; then + echo "Usage: run.sh " + exit 1 +fi + +echo "Running Cactus tests on Android..." +echo "============================" + +if ! command -v adb &>/dev/null; then + echo "adb not found" + echo "Install Android SDK Platform Tools and ensure it's in your PATH" + echo "Installation:" + echo " - Via Android Studio: Settings > Android SDK > SDK Tools > Android SDK Platform-Tools" + exit 1 +fi + +echo "" +echo "Step 1: Selecting Android device..." + +adb start-server + +connected_devices=$(adb devices | grep -E "device$|emulator" | grep -v "^List" | awk '{print $1}') + +if command -v emulator &>/dev/null; then + available_emulators=$(emulator -list-avds | grep -v "^INFO" || true) +else + available_emulators="" +fi + +all_devices="" + +if [ -n "$connected_devices" ]; then + while read -r device_id; do + if [[ "$device_id" == emulator-* ]]; then + device_model=$(adb -s "$device_id" shell getprop ro.product.model | tr -d '\r') + device_android=$(adb -s "$device_id" shell getprop ro.build.version.release | tr -d '\r') + avd_name=$(adb -s "$device_id" shell getprop ro.kernel.qemu.avd_name | tr -d '\r') + if [ -n "$avd_name" ]; then + all_devices=$(printf "%s\n%s|emulator|%s|running|%s|%s" "$all_devices" "$avd_name" "$device_id" "$device_model" "$device_android") + else + all_devices=$(printf "%s\n%s|emulator|%s|running|%s|%s" "$all_devices" "$device_id" "$device_id" "$device_model" "$device_android") + fi + else + device_model=$(adb -s "$device_id" shell getprop ro.product.model | tr -d '\r') + device_android=$(adb -s "$device_id" shell getprop ro.build.version.release | tr -d '\r') + all_devices=$(printf "%s\n%s|device|%s|running|%s|%s" "$all_devices" "$device_model" "$device_id" "$device_model" "$device_android") + fi + done <<< "$connected_devices" +fi + +if [ -n "$available_emulators" ]; then + while read -r avd_name; do + if ! echo "$all_devices" | grep -q "^$avd_name|emulator|"; then + all_devices=$(printf "%s\n%s|emulator||offline||" "$all_devices" "$avd_name") + fi + done <<< "$available_emulators" +fi + +all_devices=$(echo "$all_devices" | grep -v '^$') + +if [ -z "$all_devices" ]; then + echo "No devices or emulators found" + echo "To use an emulator:" + echo " - Create one through Android Studio AVD Manager" + echo " - Or start one with: emulator -avd " + echo "To use a physical device:" + echo " - Connect via USB" + echo " - Enable USB debugging in Developer Options" + echo " - Authorize the computer when prompted" + exit 1 +fi + +physical_count=$(echo "$all_devices" | grep -c '|device|' || true) +device_num=0 + +if [ "$physical_count" -gt 0 ]; then + echo "Devices:" + while IFS='|' read -r name type device_id status model android_version; do + if [ "$type" = "device" ]; then + device_num=$((device_num + 1)) + if [ -n "$android_version" ]; then + printf " %2d. %s (Android %s)\n" "$device_num" "$name" "$android_version" + else + printf " %2d. %s\n" "$device_num" "$name" + fi + fi + done <<< "$all_devices" + echo "" +fi + +echo "Emulators:" +while IFS='|' read -r name type device_id status model android_version; do + if [ "$type" = "emulator" ]; then + device_num=$((device_num + 1)) + if [ "$status" = "offline" ]; then + printf " %2d. %s [not running]\n" "$device_num" "$name" + else + if [ -n "$android_version" ]; then + printf " %2d. %s (Android %s)\n" "$device_num" "$name" "$android_version" + else + printf " %2d. %s\n" "$device_num" "$name" + fi + fi + fi +done <<< "$all_devices" + +echo "" +read -p "Select device number (1-$device_num): " device_number + +if ! [[ "$device_number" =~ ^[0-9]+$ ]] || [ "$device_number" -lt 1 ] || [ "$device_number" -gt "$device_num" ]; then + echo "Invalid selection" + exit 1 +fi + +selected_line=$(echo "$all_devices" | sed -n "${device_number}p") +device_name=$(echo "$selected_line" | cut -d'|' -f1) +device_type=$(echo "$selected_line" | cut -d'|' -f2) +DEVICE_ID=$(echo "$selected_line" | cut -d'|' -f3) +device_status=$(echo "$selected_line" | cut -d'|' -f4) + +if [ -z "$device_name" ]; then + echo "Could not parse device information" + exit 1 +fi + +echo "" +if [ "$device_type" = "emulator" ]; then + if [ "$device_status" = "offline" ]; then + echo "Selected: $device_name (Emulator - Not Running)" + echo "Starting emulator..." + + if ! command -v emulator &>/dev/null; then + echo "Emulator command not found" + echo "Add Android SDK emulator to your PATH" + exit 1 + fi + + emulator -avd "$device_name" -no-snapshot-load & + emulator_pid=$! + + echo "Waiting for emulator to boot..." + timeout=300 + elapsed=0 + while [ $elapsed -lt $timeout ]; do + sleep 2 + elapsed=$((elapsed + 2)) + + DEVICE_ID=$(adb devices | grep emulator | head -1 | awk '{print $1}') + + if [ -n "$DEVICE_ID" ]; then + boot_complete=$(adb -s "$DEVICE_ID" shell getprop sys.boot_completed | tr -d '\r') + if [ "$boot_complete" = "1" ]; then + echo "Emulator started successfully" + break + fi + fi + done + + if [ -z "$DEVICE_ID" ] || [ "$boot_complete" != "1" ]; then + echo "Failed to start emulator (timeout)" + exit 1 + fi + else + echo "Selected: $device_name (Emulator)" + fi +else + echo "Selected: $device_name (Device)" +fi + +if ! adb -s "$DEVICE_ID" shell echo "test" &>/dev/null; then + echo "Device not responding" + echo "Ensure the device is connected and USB debugging is authorized" + exit 1 +fi + +echo "" +echo "Step 2: Building Cactus static library for Android..." + +if [ -z "$ANDROID_NDK_HOME" ]; then + if [ -n "$ANDROID_HOME" ]; then + ANDROID_NDK_HOME=$(ls -d "$ANDROID_HOME/ndk/"* 2>/dev/null | sort -V | tail -1) + elif [ -d "$HOME/Library/Android/sdk" ]; then + ANDROID_NDK_HOME=$(ls -d "$HOME/Library/Android/sdk/ndk/"* 2>/dev/null | sort -V | tail -1) + fi +fi + +if [ -z "$ANDROID_NDK_HOME" ] || [ ! -d "$ANDROID_NDK_HOME" ]; then + echo "Android NDK not found" + echo "Install the NDK through Android Studio: Settings > Android SDK > SDK Tools > NDK" + exit 1 +fi + +cmake_toolchain="$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake" +android_platform=${ANDROID_PLATFORM:-android-21} +android_lib_build_dir="$PROJECT_ROOT/android/build" +n_jobs=$(nproc 2>/dev/null || sysctl -n hw.logicalcpu 2>/dev/null || echo 4) + +cmake -DCMAKE_TOOLCHAIN_FILE="$cmake_toolchain" \ + -DANDROID_ABI="arm64-v8a" \ + -DANDROID_PLATFORM="$android_platform" \ + -DCMAKE_BUILD_TYPE=Release \ + -DCACTUS_CURL_ROOT="$CACTUS_CURL_ROOT" \ + -S "$PROJECT_ROOT/android" \ + -B "$android_lib_build_dir" >/dev/null + +if ! cmake --build "$android_lib_build_dir" --target cactus_static -j "$n_jobs" >/dev/null; then + echo "Failed to build Cactus static library" + exit 1 +fi + +if [ ! -f "$android_lib_build_dir/lib/libcactus_static.a" ]; then + echo "Static library not found at $android_lib_build_dir/lib/libcactus_static.a" + exit 1 +fi +echo "Static library built: $android_lib_build_dir/lib/libcactus_static.a" + +echo "" +echo "Step 3: Building Android tests..." + +android_test_dir="$SCRIPT_DIR" +android_build_dir="$android_test_dir/build" + +rm -rf "$android_build_dir" +mkdir -p "$android_build_dir" + +if ! cmake -S "$android_test_dir" -B "$android_build_dir" \ + -DCMAKE_TOOLCHAIN_FILE="$cmake_toolchain" \ + -DANDROID_ABI="arm64-v8a" \ + -DANDROID_PLATFORM="$android_platform" \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_RULE_MESSAGES=OFF \ + -DCMAKE_VERBOSE_MAKEFILE=OFF; then + echo "Failed to configure tests" + exit 1 +fi + +if ! cmake --build "$android_build_dir" -j "$n_jobs"; then + echo "Failed to build tests" + exit 1 +fi + +echo "Discovering test executables..." +all_test_executables=($(find "$android_build_dir" -maxdepth 1 -name "test_*" -type f | sort)) + +if [ ${#all_test_executables[@]} -eq 0 ]; then + echo "No test executables found" + exit 1 +fi + +test_executables=() +for test_exe in "${all_test_executables[@]}"; do + test_name=$(basename "$test_exe" | sed 's/^test_//') + if [ -z "${CACTUS_TEST_ONLY:-}" ] || [ "$test_name" = "$CACTUS_TEST_ONLY" ]; then + test_executables+=("$test_exe") + fi +done + +if [ ${#test_executables[@]} -eq 0 ]; then + echo "No test executables match filter: $CACTUS_TEST_ONLY" + exit 1 +fi + +echo "Found ${#test_executables[@]} test executable(s)" + +echo "" +echo "Step 4: Deploying to device..." + +model_src="$MODEL_NAME" +model_dir=$(basename "$model_src") +assets_src="$PROJECT_ROOT/cactus-engine/tests/assets" + +device_test_dir="/data/local/tmp/cactus_tests" +device_model_dir="/data/local/tmp/cactus_models" +device_assets_dir="/data/local/tmp/cactus_assets" + +adb -s "$DEVICE_ID" shell "mkdir -p $device_test_dir $device_model_dir $device_assets_dir" + +echo "Pushing model weights..." +adb -s "$DEVICE_ID" push "$model_src" "$device_model_dir/" + +if [ -d "$assets_src" ]; then + echo "Pushing test assets..." + adb -s "$DEVICE_ID" push "$assets_src" "$device_assets_dir/" +fi + +echo "Pushing test executables..." +for test_exe in "${test_executables[@]}"; do + test_name=$(basename "$test_exe") + adb -s "$DEVICE_ID" push "$test_exe" "$device_test_dir/" + adb -s "$DEVICE_ID" shell "chmod +x $device_test_dir/$test_name" +done + +echo "" +echo "Step 5: Running tests..." +echo "------------------------" +echo "Using model path: $device_model_dir/$model_dir" +echo "Using assets path: $device_assets_dir/assets" + +FAILED=0 +for test_exe in "${test_executables[@]}"; do + test_name=$(basename "$test_exe") + echo "" + echo "Running $test_name..." + + if ! adb -s "$DEVICE_ID" shell "cd $device_test_dir && \ + export CACTUS_TEST_MODEL=$device_model_dir/$model_dir && \ + export CACTUS_TEST_ASSETS=$device_assets_dir/assets && \ + export CACTUS_INDEX_PATH=$device_assets_dir/assets && \ + export CACTUS_NO_CLOUD_TELE=${CACTUS_NO_CLOUD_TELE:-1} && \ + ./$test_name"; then + FAILED=1 + fi +done + +echo "" +if [ $FAILED -eq 0 ]; then + echo "All tests passed." +else + echo "Some tests failed." +fi + +exit $FAILED diff --git a/cactus-engine/tests/ios/.gitignore b/cactus-engine/tests/ios/.gitignore new file mode 100644 index 000000000..143f8b56e --- /dev/null +++ b/cactus-engine/tests/ios/.gitignore @@ -0,0 +1,4 @@ +CactusTest/CactusTest.xcodeproj/* +!CactusTest/CactusTest.xcodeproj/project.pbxproj.template +CactusTest/CactusTest/AppDelegate.mm +build/ diff --git a/cactus-engine/tests/ios/CactusTest/CactusTest.xcodeproj/project.pbxproj.template b/cactus-engine/tests/ios/CactusTest/CactusTest.xcodeproj/project.pbxproj.template new file mode 100644 index 000000000..aea0cf79a --- /dev/null +++ b/cactus-engine/tests/ios/CactusTest/CactusTest.xcodeproj/project.pbxproj.template @@ -0,0 +1,334 @@ +// !$*UTF8*$! +{ + archiveVersion = 1; + classes = { + }; + objectVersion = 77; + objects = { + +/* Begin PBXFileReference section */ + 2AA889CA2EE510D50037A29D /* CactusTest.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = CactusTest.app; sourceTree = BUILT_PRODUCTS_DIR; }; +/* End PBXFileReference section */ + +/* Begin PBXFileSystemSynchronizedBuildFileExceptionSet section */ + 2AA889E12EE510D60037A29D /* Exceptions for "CactusTest" folder in "CactusTest" target */ = { + isa = PBXFileSystemSynchronizedBuildFileExceptionSet; + membershipExceptions = ( + Info.plist, + ); + target = 2AA889C92EE510D50037A29D /* CactusTest */; + }; +/* End PBXFileSystemSynchronizedBuildFileExceptionSet section */ + +/* Begin PBXFileSystemSynchronizedRootGroup section */ + 2AA889CC2EE510D50037A29D /* CactusTest */ = { + isa = PBXFileSystemSynchronizedRootGroup; + exceptions = ( + 2AA889E12EE510D60037A29D /* Exceptions for "CactusTest" folder in "CactusTest" target */, + ); + path = CactusTest; + sourceTree = ""; + }; +/* End PBXFileSystemSynchronizedRootGroup section */ + +/* Begin PBXFrameworksBuildPhase section */ + 2AA889C72EE510D50037A29D /* Frameworks */ = { + isa = PBXFrameworksBuildPhase; + buildActionMask = 2147483647; + files = ( + ); + runOnlyForDeploymentPostprocessing = 0; + }; +/* End PBXFrameworksBuildPhase section */ + +/* Begin PBXGroup section */ + 2AA889C12EE510D50037A29D = { + isa = PBXGroup; + children = ( + 2AA889CC2EE510D50037A29D /* CactusTest */, + 2AA889CB2EE510D50037A29D /* Products */, + ); + sourceTree = ""; + }; + 2AA889CB2EE510D50037A29D /* Products */ = { + isa = PBXGroup; + children = ( + 2AA889CA2EE510D50037A29D /* CactusTest.app */, + ); + name = Products; + sourceTree = ""; + }; +/* End PBXGroup section */ + +/* Begin PBXNativeTarget section */ + 2AA889C92EE510D50037A29D /* CactusTest */ = { + isa = PBXNativeTarget; + buildConfigurationList = 2AA889E22EE510D60037A29D /* Build configuration list for PBXNativeTarget "CactusTest" */; + buildPhases = ( + 2AA889C62EE510D50037A29D /* Sources */, + 2AA889C72EE510D50037A29D /* Frameworks */, + 2AA889C82EE510D50037A29D /* Resources */, + ); + buildRules = ( + ); + dependencies = ( + ); + fileSystemSynchronizedGroups = ( + 2AA889CC2EE510D50037A29D /* CactusTest */, + ); + name = CactusTest; + packageProductDependencies = ( + ); + productName = CactusTest; + productReference = 2AA889CA2EE510D50037A29D /* CactusTest.app */; + productType = "com.apple.product-type.application"; + }; +/* End PBXNativeTarget section */ + +/* Begin PBXProject section */ + 2AA889C22EE510D50037A29D /* Project object */ = { + isa = PBXProject; + attributes = { + BuildIndependentTargetsInParallel = 1; + LastUpgradeCheck = 2600; + TargetAttributes = { + 2AA889C92EE510D50037A29D = { + CreatedOnToolsVersion = 26.0.1; + }; + }; + }; + buildConfigurationList = 2AA889C52EE510D50037A29D /* Build configuration list for PBXProject "CactusTest" */; + developmentRegion = en; + hasScannedForEncodings = 0; + knownRegions = ( + en, + Base, + ); + mainGroup = 2AA889C12EE510D50037A29D; + minimizedProjectReferenceProxies = 1; + preferredProjectObjectVersion = 77; + productRefGroup = 2AA889CB2EE510D50037A29D /* Products */; + projectDirPath = ""; + projectRoot = ""; + targets = ( + 2AA889C92EE510D50037A29D /* CactusTest */, + ); + }; +/* End PBXProject section */ + +/* Begin PBXResourcesBuildPhase section */ + 2AA889C82EE510D50037A29D /* Resources */ = { + isa = PBXResourcesBuildPhase; + buildActionMask = 2147483647; + files = ( + ); + runOnlyForDeploymentPostprocessing = 0; + }; +/* End PBXResourcesBuildPhase section */ + +/* Begin PBXSourcesBuildPhase section */ + 2AA889C62EE510D50037A29D /* Sources */ = { + isa = PBXSourcesBuildPhase; + buildActionMask = 2147483647; + files = ( + ); + runOnlyForDeploymentPostprocessing = 0; + }; +/* End PBXSourcesBuildPhase section */ + +/* Begin XCBuildConfiguration section */ + 2AA889E32EE510D60037A29D /* Debug */ = { + isa = XCBuildConfiguration; + buildSettings = { + ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon; + ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor; + CODE_SIGN_STYLE = Automatic; + CURRENT_PROJECT_VERSION = 1; + GENERATE_INFOPLIST_FILE = YES; + INFOPLIST_FILE = CactusTest/Info.plist; + INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES; + INFOPLIST_KEY_UILaunchStoryboardName = LaunchScreen; + INFOPLIST_KEY_UIMainStoryboardFile = Main; + INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad = "UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight"; + INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone = "UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight"; + LD_RUNPATH_SEARCH_PATHS = ( + "$(inherited)", + "@executable_path/Frameworks", + ); + MARKETING_VERSION = 1.0; + PRODUCT_BUNDLE_IDENTIFIER = cactus.CactusTest; + PRODUCT_NAME = "$(TARGET_NAME)"; + STRING_CATALOG_GENERATE_SYMBOLS = YES; + SWIFT_EMIT_LOC_STRINGS = YES; + TARGETED_DEVICE_FAMILY = "1,2"; + }; + name = Debug; + }; + 2AA889E42EE510D60037A29D /* Release */ = { + isa = XCBuildConfiguration; + buildSettings = { + ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon; + ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor; + CODE_SIGN_STYLE = Automatic; + CURRENT_PROJECT_VERSION = 1; + GENERATE_INFOPLIST_FILE = YES; + INFOPLIST_FILE = CactusTest/Info.plist; + INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES; + INFOPLIST_KEY_UILaunchStoryboardName = LaunchScreen; + INFOPLIST_KEY_UIMainStoryboardFile = Main; + INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad = "UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight"; + INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone = "UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight"; + LD_RUNPATH_SEARCH_PATHS = ( + "$(inherited)", + "@executable_path/Frameworks", + ); + MARKETING_VERSION = 1.0; + PRODUCT_BUNDLE_IDENTIFIER = cactus.CactusTest; + PRODUCT_NAME = "$(TARGET_NAME)"; + STRING_CATALOG_GENERATE_SYMBOLS = YES; + SWIFT_EMIT_LOC_STRINGS = YES; + TARGETED_DEVICE_FAMILY = "1,2"; + }; + name = Release; + }; + 2AA889E52EE510D60037A29D /* Debug */ = { + isa = XCBuildConfiguration; + buildSettings = { + ALWAYS_SEARCH_USER_PATHS = NO; + ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES; + CLANG_ANALYZER_NONNULL = YES; + CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE; + CLANG_CXX_LANGUAGE_STANDARD = "gnu++20"; + CLANG_ENABLE_MODULES = YES; + CLANG_ENABLE_OBJC_ARC = YES; + CLANG_ENABLE_OBJC_WEAK = YES; + CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES; + CLANG_WARN_BOOL_CONVERSION = YES; + CLANG_WARN_COMMA = YES; + CLANG_WARN_CONSTANT_CONVERSION = YES; + CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES; + CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR; + CLANG_WARN_DOCUMENTATION_COMMENTS = YES; + CLANG_WARN_EMPTY_BODY = YES; + CLANG_WARN_ENUM_CONVERSION = YES; + CLANG_WARN_INFINITE_RECURSION = YES; + CLANG_WARN_INT_CONVERSION = YES; + CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES; + CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES; + CLANG_WARN_OBJC_LITERAL_CONVERSION = YES; + CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR; + CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES; + CLANG_WARN_RANGE_LOOP_ANALYSIS = YES; + CLANG_WARN_STRICT_PROTOTYPES = YES; + CLANG_WARN_SUSPICIOUS_MOVE = YES; + CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE; + CLANG_WARN_UNREACHABLE_CODE = YES; + CLANG_WARN__DUPLICATE_METHOD_MATCH = YES; + COPY_PHASE_STRIP = NO; + DEBUG_INFORMATION_FORMAT = dwarf; + ENABLE_STRICT_OBJC_MSGSEND = YES; + ENABLE_TESTABILITY = YES; + ENABLE_USER_SCRIPT_SANDBOXING = YES; + GCC_C_LANGUAGE_STANDARD = gnu17; + GCC_DYNAMIC_NO_PIC = NO; + GCC_NO_COMMON_BLOCKS = YES; + GCC_OPTIMIZATION_LEVEL = 0; + GCC_PREPROCESSOR_DEFINITIONS = ( + "DEBUG=1", + "$(inherited)", + ); + GCC_WARN_64_TO_32_BIT_CONVERSION = YES; + GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR; + GCC_WARN_UNDECLARED_SELECTOR = YES; + GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE; + GCC_WARN_UNUSED_FUNCTION = YES; + GCC_WARN_UNUSED_VARIABLE = YES; + IPHONEOS_DEPLOYMENT_TARGET = 26.0; + LOCALIZATION_PREFERS_STRING_CATALOGS = YES; + MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE; + MTL_FAST_MATH = YES; + ONLY_ACTIVE_ARCH = YES; + SDKROOT = iphoneos; + }; + name = Debug; + }; + 2AA889E62EE510D60037A29D /* Release */ = { + isa = XCBuildConfiguration; + buildSettings = { + ALWAYS_SEARCH_USER_PATHS = NO; + ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES; + CLANG_ANALYZER_NONNULL = YES; + CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE; + CLANG_CXX_LANGUAGE_STANDARD = "gnu++20"; + CLANG_ENABLE_MODULES = YES; + CLANG_ENABLE_OBJC_ARC = YES; + CLANG_ENABLE_OBJC_WEAK = YES; + CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES; + CLANG_WARN_BOOL_CONVERSION = YES; + CLANG_WARN_COMMA = YES; + CLANG_WARN_CONSTANT_CONVERSION = YES; + CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES; + CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR; + CLANG_WARN_DOCUMENTATION_COMMENTS = YES; + CLANG_WARN_EMPTY_BODY = YES; + CLANG_WARN_ENUM_CONVERSION = YES; + CLANG_WARN_INFINITE_RECURSION = YES; + CLANG_WARN_INT_CONVERSION = YES; + CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES; + CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES; + CLANG_WARN_OBJC_LITERAL_CONVERSION = YES; + CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR; + CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES; + CLANG_WARN_RANGE_LOOP_ANALYSIS = YES; + CLANG_WARN_STRICT_PROTOTYPES = YES; + CLANG_WARN_SUSPICIOUS_MOVE = YES; + CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE; + CLANG_WARN_UNREACHABLE_CODE = YES; + CLANG_WARN__DUPLICATE_METHOD_MATCH = YES; + COPY_PHASE_STRIP = NO; + DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym"; + ENABLE_NS_ASSERTIONS = NO; + ENABLE_STRICT_OBJC_MSGSEND = YES; + ENABLE_USER_SCRIPT_SANDBOXING = YES; + GCC_C_LANGUAGE_STANDARD = gnu17; + GCC_NO_COMMON_BLOCKS = YES; + GCC_WARN_64_TO_32_BIT_CONVERSION = YES; + GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR; + GCC_WARN_UNDECLARED_SELECTOR = YES; + GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE; + GCC_WARN_UNUSED_FUNCTION = YES; + GCC_WARN_UNUSED_VARIABLE = YES; + IPHONEOS_DEPLOYMENT_TARGET = 26.0; + LOCALIZATION_PREFERS_STRING_CATALOGS = YES; + MTL_ENABLE_DEBUG_INFO = NO; + MTL_FAST_MATH = YES; + SDKROOT = iphoneos; + VALIDATE_PRODUCT = YES; + }; + name = Release; + }; +/* End XCBuildConfiguration section */ + +/* Begin XCConfigurationList section */ + 2AA889C52EE510D50037A29D /* Build configuration list for PBXProject "CactusTest" */ = { + isa = XCConfigurationList; + buildConfigurations = ( + 2AA889E52EE510D60037A29D /* Debug */, + 2AA889E62EE510D60037A29D /* Release */, + ); + defaultConfigurationIsVisible = 0; + defaultConfigurationName = Release; + }; + 2AA889E22EE510D60037A29D /* Build configuration list for PBXNativeTarget "CactusTest" */ = { + isa = XCConfigurationList; + buildConfigurations = ( + 2AA889E32EE510D60037A29D /* Debug */, + 2AA889E42EE510D60037A29D /* Release */, + ); + defaultConfigurationIsVisible = 0; + defaultConfigurationName = Release; + }; +/* End XCConfigurationList section */ + }; + rootObject = 2AA889C22EE510D50037A29D /* Project object */; +} diff --git a/cactus-engine/tests/ios/CactusTest/CactusTest/AppDelegate.h b/cactus-engine/tests/ios/CactusTest/CactusTest/AppDelegate.h new file mode 100644 index 000000000..25a0c524a --- /dev/null +++ b/cactus-engine/tests/ios/CactusTest/CactusTest/AppDelegate.h @@ -0,0 +1,5 @@ +#import + +@interface AppDelegate : UIResponder + +@end diff --git a/cactus-engine/tests/ios/CactusTest/CactusTest/Info.plist b/cactus-engine/tests/ios/CactusTest/CactusTest/Info.plist new file mode 100644 index 000000000..6631ffa6f --- /dev/null +++ b/cactus-engine/tests/ios/CactusTest/CactusTest/Info.plist @@ -0,0 +1,6 @@ + + + + + + diff --git a/cactus-engine/tests/ios/CactusTest/CactusTest/main.m b/cactus-engine/tests/ios/CactusTest/CactusTest/main.m new file mode 100644 index 000000000..3631c9476 --- /dev/null +++ b/cactus-engine/tests/ios/CactusTest/CactusTest/main.m @@ -0,0 +1,10 @@ +#import +#import "AppDelegate.h" + +int main(int argc, char * argv[]) { + NSString * appDelegateClassName; + @autoreleasepool { + appDelegateClassName = NSStringFromClass([AppDelegate class]); + } + return UIApplicationMain(argc, argv, nil, appDelegateClassName); +} diff --git a/cactus-engine/tests/ios/configure_xcode.rb b/cactus-engine/tests/ios/configure_xcode.rb new file mode 100755 index 000000000..051503849 --- /dev/null +++ b/cactus-engine/tests/ios/configure_xcode.rb @@ -0,0 +1,239 @@ +#!/usr/bin/env ruby +require 'xcodeproj' + +def fail_with(message) + STDERR.puts "Error: #{message}" + exit 1 +end + +def generate_app_delegate(output_path, test_files) + raw_level = ENV.fetch('CACTUS_TEST_LOG_LEVEL', 'WARN').to_s.upcase + level_int = case raw_level + when 'DEBUG' then 0 + when 'INFO' then 1 + when 'WARN' then 2 + when 'ERROR' then 3 + when 'NONE' then 4 + else 2 + end + + test_names = test_files.map { |f| File.basename(f, '.cpp') } + extern_declarations = test_names.map { |name| "extern int #{name}_main();" }.join("\n") + test_calls = test_names.map { |name| + filter_name = name.sub(/^test_/, '') + " if (should_run(\"#{filter_name}\")) #{name}_main();" + }.join("\n") + + app_delegate_content = <<~OBJC + +#import "AppDelegate.h" +#import +#import +#include "cactus.h" +#include + +#{extern_declarations} + +@implementation AppDelegate + +- (void)copyFromBundle:(NSString *)bundlePath toDocuments:(const char *)name { + if (!name) return; + NSFileManager *fileManager = [NSFileManager defaultManager]; + NSString *itemName = [NSString stringWithUTF8String:name]; + NSString *sourceItemPath = [NSString stringWithFormat:@"%@/%@", bundlePath, itemName]; + if (![fileManager fileExistsAtPath:sourceItemPath]) { + fprintf(stderr, "[CactusTest] copyFromBundle: source not found: %s\\n", [sourceItemPath UTF8String]); + return; + } + if ([fileManager fileExistsAtPath:itemName]) { + NSError *removeError = nil; + [fileManager removeItemAtPath:itemName error:&removeError]; + } + NSError *copyError = nil; + [fileManager copyItemAtPath:sourceItemPath toPath:itemName error:©Error]; + if (copyError) { + fprintf(stderr, "[CactusTest] copyFromBundle: failed to copy %s -> %s: %s\\n", + [sourceItemPath UTF8String], [itemName UTF8String], [[copyError localizedDescription] UTF8String]); + } +} + +- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { + NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); + NSString *documentsDirectory = paths[0]; + chdir([documentsDirectory UTF8String]); + +#if !TARGET_OS_SIMULATOR + freopen("cactus_test.log", "w", stdout); + freopen("cactus_test.log", "a", stderr); + setbuf(stdout, NULL); + setbuf(stderr, NULL); +#endif + + cactus_log_set_level(#{level_int}); + + NSString *bundlePath = [[NSBundle mainBundle] bundlePath]; + [self copyFromBundle:bundlePath toDocuments:getenv("CACTUS_TEST_MODEL")]; + [self copyFromBundle:bundlePath toDocuments:getenv("CACTUS_TEST_ASSETS")]; + + dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(NSEC_PER_SEC)), dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{ + const char* only = getenv("CACTUS_TEST_ONLY"); + std::string filter = (only && only[0]) ? std::string(only) : ""; + auto should_run = [&](const char* name) { + return filter.empty() || filter == name; + }; + + #{test_calls} + + exit(0); + }); + + return YES; +} + +@end + +OBJC + + File.write(output_path, app_delegate_content) + puts "Generated AppDelegate.mm with #{test_names.length} test(s)" +end + +project_root = ENV['PROJECT_ROOT'] +tests_root = ENV['TESTS_ROOT'] +project_path = ENV['XCODEPROJ_PATH'] +bundle_id = ENV['BUNDLE_ID'] +team_id = ENV['DEVELOPMENT_TEAM'] +device_type = ENV['DEVICE_TYPE'] + +fail_with("PROJECT_ROOT not set") unless project_root +fail_with("TESTS_ROOT not set") unless tests_root +fail_with("XCODEPROJ_PATH not set") unless project_path +fail_with("DEVICE_TYPE not set (should be 'device' or 'simulator')") unless device_type +fail_with("Xcode project not found") unless File.exist?(project_path) + +project = Xcodeproj::Project.open(project_path) rescue fail_with("Failed to open Xcode project") +target = project.targets.first or fail_with("No targets found") + +tests_group = project.main_group.find_subpath('Tests', true) +tests_group.set_path(tests_root) +tests_group.set_source_tree('') + +discovered_test_files = Dir.glob(File.join(tests_root, 'test_*.cpp')) + .reject { |f| File.basename(f) == 'test_utils.cpp' } + .sort + .map { |f| File.basename(f) } + +puts "Discovered #{discovered_test_files.length} test file(s):" +discovered_test_files.each { |f| puts " - #{f}" } + +test_files = {} +discovered_test_files.each { |f| test_files[f] = "#{File.basename(f, '.cpp')}_main" } +test_files['test_utils.cpp'] = nil + +test_files.each do |filename, renamed_main| + file_path = File.join(tests_root, filename) + next unless File.exist?(file_path) + existing = tests_group.files.find { |f| f.path == filename || f.real_path&.to_s == file_path } + file_ref = existing || begin + ref = tests_group.new_reference(file_path) + ref.set_source_tree('') + ref + end + build_file = target.source_build_phase.files.find { |bf| bf.file_ref == file_ref } + build_file ||= target.source_build_phase.add_file_reference(file_ref) + build_file.settings = { 'COMPILER_FLAGS' => "-Dmain=#{renamed_main}" } if renamed_main +end + +unless tests_group.files.any? { |f| f.path == 'test_utils.h' } + ref = tests_group.new_reference(File.join(tests_root, 'test_utils.h')) + ref.set_source_tree('') +end + +generate_app_delegate(File.join(File.dirname(project_path), 'CactusTest', 'AppDelegate.mm'), discovered_test_files) + +cactus_sources_group = project.main_group.groups.find { |g| g.name == 'CactusSources' } +if cactus_sources_group + cactus_sources_group.files.each do |f| + bf = target.source_build_phase.files.find { |b| b.file_ref == f } + target.source_build_phase.files.delete(bf) if bf + end + cactus_sources_group.clear + cactus_sources_group.remove_from_project +end + +apple_dir = File.join(project_root, 'apple') +static_lib_path = device_type == 'simulator' ? + File.join(apple_dir, 'libcactus-simulator.a') : + File.join(apple_dir, 'libcactus-device.a') + +fail_with("Static library not found at: #{static_lib_path}") unless File.exist?(static_lib_path) +puts "Using static library: #{static_lib_path}" + +cactus_dir = File.join(project_root, 'cactus') +cactus_engine_dir = File.join(project_root, 'cactus-engine') +cactus_graph_dir = File.join(project_root, 'cactus-graph') +cactus_kernels_dir = File.join(project_root, 'cactus-kernels') + +curl_root = ENV['CACTUS_CURL_ROOT'] +vendored_curl_lib = nil +if curl_root && !curl_root.empty? + vendored_curl_lib = device_type == 'simulator' ? + File.join(curl_root, 'ios', 'simulator', 'libcurl.a') : + File.join(curl_root, 'ios', 'device', 'libcurl.a') + if File.exist?(vendored_curl_lib) + puts "Using vendored iOS libcurl: #{vendored_curl_lib}" + else + vendored_curl_lib = nil + puts "Vendored iOS libcurl not found under CACTUS_CURL_ROOT=#{curl_root}; continuing without explicit curl link" + end +end + +target.frameworks_build_phase.files.to_a.each do |build_file| + if build_file.file_ref&.path&.to_s&.include?('libcactus') + target.frameworks_build_phase.files.delete(build_file) + end +end + +libs_group = project.main_group.groups.find { |g| g.name == 'Frameworks' } +if libs_group + libs_group.files.to_a.each do |f| + f.remove_from_project if f.path&.to_s&.include?('libcactus') + end +end + +target.build_configurations.each do |config| + config.build_settings['HEADER_SEARCH_PATHS'] ||= ['$(inherited)'] + [tests_root, cactus_dir, cactus_engine_dir, cactus_graph_dir, cactus_kernels_dir].each do |path| + config.build_settings['HEADER_SEARCH_PATHS'] << path unless config.build_settings['HEADER_SEARCH_PATHS'].include?(path) + end + if curl_root && !curl_root.empty? + curl_include = File.join(curl_root, 'include') + if File.exist?(File.join(curl_include, 'curl', 'curl.h')) + config.build_settings['HEADER_SEARCH_PATHS'] << curl_include unless config.build_settings['HEADER_SEARCH_PATHS'].include?(curl_include) + end + end + + config.build_settings['CLANG_CXX_LANGUAGE_STANDARD'] = 'c++20' + config.build_settings['CLANG_CXX_LIBRARY'] = 'libc++' + config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0' + config.build_settings['CODE_SIGN_STYLE'] = 'Automatic' + config.build_settings['PRODUCT_BUNDLE_IDENTIFIER'] = bundle_id if bundle_id + config.build_settings['DEVELOPMENT_TEAM'] = team_id if team_id + config.build_settings.delete('INFOPLIST_KEY_UILaunchStoryboardName') + config.build_settings.delete('INFOPLIST_KEY_UIMainStoryboardFile') + + config.build_settings['OTHER_CPLUSPLUSFLAGS'] = ['$(inherited)', '-pthread', '-Wall', '-Wextra', '-pedantic', '-O3'] + + config.build_settings['OTHER_LDFLAGS'] ||= ['$(inherited)'] + config.build_settings['OTHER_LDFLAGS'].reject! { |flag| flag.to_s.include?('libcactus') } + config.build_settings['OTHER_LDFLAGS'] << static_lib_path + + ['-framework CoreML', '-framework Foundation', '-framework Accelerate', '-framework Security', '-framework SystemConfiguration', '-framework CFNetwork'].each do |framework| + config.build_settings['OTHER_LDFLAGS'] << framework unless config.build_settings['OTHER_LDFLAGS'].include?(framework) + end + if vendored_curl_lib + config.build_settings['OTHER_LDFLAGS'] << vendored_curl_lib unless config.build_settings['OTHER_LDFLAGS'].include?(vendored_curl_lib) + end +end + +project.save rescue fail_with("Failed to save Xcode project") diff --git a/cactus-engine/tests/ios/run.sh b/cactus-engine/tests/ios/run.sh new file mode 100755 index 000000000..e9ddd05f9 --- /dev/null +++ b/cactus-engine/tests/ios/run.sh @@ -0,0 +1,430 @@ +#!/bin/bash + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)" +CACTUS_CURL_ROOT="${CACTUS_CURL_ROOT:-$PROJECT_ROOT/cactus-engine/libs/curl}" +export CACTUS_CURL_ROOT + +MODEL_NAME="$1" + +if [ -z "$MODEL_NAME" ]; then + echo "Usage: run.sh " + exit 1 +fi + +echo "Running Cactus tests on iOS..." +echo "============================" + +if [ ! -d "/Applications/Xcode.app" ]; then + echo "Xcode not installed" + echo "Install Xcode from the Mac App Store" + exit 1 +fi + +if ! xcode-select -p &>/dev/null; then + echo "Xcode Command Line Tools not installed" + echo "Install with: xcode-select --install" + exit 1 +fi + +if ! /usr/bin/xcrun --version &>/dev/null; then + echo "Xcode license not accepted" + echo "Accept the license with: sudo xcodebuild -license accept" + exit 1 +fi + +if ! command -v xcodebuild &>/dev/null; then + echo "xcodebuild not found" + exit 1 +fi + +echo "" +echo "Step 1: Selecting iOS device..." + +simulators=$(xcrun simctl list devices available | grep -E "^\s+(iPhone|iPad)" | grep -v "unavailable" | sed 's/^[[:space:]]*//' | while read line; do + uuid=$(echo "$line" | grep -oE '\([A-F0-9-]{36}\)' | head -1 | tr -d '()') + if [ -n "$uuid" ]; then + name=$(echo "$line" | sed -E 's/ \([^)]*\)//g' | xargs) + echo "${name}|simulator|${uuid}" + fi +done) + +xctrace_output=$(xcrun xctrace list devices 2>&1) + +physical_devices=$(echo "$xctrace_output" | awk ' + /== Devices ==/ { in_online=1; in_offline=0; next } + /== Devices Offline ==/ { in_online=0; in_offline=1; next } + /== Simulators ==/ { exit } + /00008[A-F0-9]{3}-[A-F0-9]{16}/ { + if (in_online || in_offline) { + status = in_offline ? "offline" : "" + print $0 "|" status + } + } +' | while read line; do + uuid=$(echo "$line" | grep -oE '00008[A-F0-9]{3}-[A-F0-9]{16}') + status=$(echo "$line" | awk -F'|' '{print $2}') + if [ -n "$uuid" ]; then + name=$(echo "$line" | awk -F'|' '{print $1}' | sed -E 's/ \([0-9]+\.[0-9]+.*$//' | xargs) + ios_version=$(echo "$line" | awk -F'|' '{print $1}' | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1) + echo "${name} (iOS ${ios_version})|device|${uuid}|${status}" + fi +done) + +all_devices=$(printf "%s\n%s\n" "$physical_devices" "$simulators" | grep -v '^$') + +if [ -z "$all_devices" ]; then + echo "No devices or simulators found" + echo "To use a simulator:" + echo " - Install iOS simulators through Xcode" + echo "To use a physical device:" + echo " - Connect via USB or network" + echo " - Enable Developer Mode in Settings" + exit 1 +fi + +physical_count=$(echo "$all_devices" | grep -c '|device|' || true) +device_num=0 + +if [ "$physical_count" -gt 0 ]; then + echo "Devices:" + while IFS='|' read -r name type uuid status; do + if [ "$type" = "device" ]; then + device_num=$((device_num + 1)) + if [ "$status" = "offline" ]; then + printf " %2d. %s [offline]\n" "$device_num" "$name" + else + printf " %2d. %s\n" "$device_num" "$name" + fi + fi + done <<< "$all_devices" + echo "" +fi + +echo "Simulators:" +while IFS='|' read -r name type uuid status; do + if [ "$type" = "simulator" ]; then + device_num=$((device_num + 1)) + printf " %2d. %s\n" "$device_num" "$name" + fi +done <<< "$all_devices" + +echo "" +read -p "Select device number (1-$device_num): " device_number + +if ! [[ "$device_number" =~ ^[0-9]+$ ]] || [ "$device_number" -lt 1 ] || [ "$device_number" -gt "$device_num" ]; then + echo "Invalid selection" + exit 1 +fi + +selected_line=$(echo "$all_devices" | sed -n "${device_number}p") +device_name=$(echo "$selected_line" | cut -d'|' -f1) +device_type=$(echo "$selected_line" | cut -d'|' -f2) +device_uuid=$(echo "$selected_line" | cut -d'|' -f3) +device_status=$(echo "$selected_line" | cut -d'|' -f4) + +if [ -z "$device_uuid" ]; then + echo "Could not parse device information" + exit 1 +fi + +echo "" +if [ "$device_type" = "simulator" ]; then + echo "Selected: $device_name (Simulator)" +else + if [ "$device_status" = "offline" ]; then + echo "Selected: $device_name (Device - Offline)" + echo "Warning: This device is currently offline" + echo "Ensure the device is:" + echo " - Connected via USB or network" + echo " - Unlocked and trusted" + echo " - Has Developer Mode enabled" + echo "" + read -p "Continue anyway? (y/N): " continue_choice + if [[ ! "$continue_choice" =~ ^[Yy]$ ]]; then + echo "Aborted" + exit 0 + fi + else + echo "Selected: $device_name (Device)" + fi + + matching_identity=$(security find-identity -p codesigning 2>/dev/null | grep "Apple Development" | head -1 || true) + valid_identity=$(security find-identity -v -p codesigning 2>/dev/null | grep "Apple Development" | head -1 || true) + + if [ -z "$matching_identity" ]; then + echo "No development certificates found" + echo "To fix this:" + echo " 1. Open Xcode > Settings > Accounts" + echo " 2. Add your Apple ID" + echo " 3. Download development certificates" + exit 1 + fi + + if [ -z "$valid_identity" ]; then + echo "Warning: Apple Development identity found, but macOS did not report it as a valid identity." + echo "Proceeding and letting xcodebuild attempt automatic signing anyway." + fi +fi + +echo "" +echo "Step 2: Building Cactus library for iOS..." + +if ! BUILD_STATIC=true BUILD_XCFRAMEWORK=false "$PROJECT_ROOT/apple/build.sh"; then + echo "Failed to build Cactus library" + exit 1 +fi + +echo "" +echo "Step 3: Configuring Xcode project..." + +xcodeproj_path="$SCRIPT_DIR/CactusTest/CactusTest.xcodeproj" +tests_root="$PROJECT_ROOT/cactus-engine/tests" + +project_file="$xcodeproj_path/project.pbxproj" +template_file="$xcodeproj_path/project.pbxproj.template" +echo "Copying project template..." +cp "$template_file" "$project_file" + +bundle_id="com.cactus.test.${USER}" +echo "Using Bundle ID: $bundle_id" + +if [ "$device_type" = "device" ]; then + if [ -n "$DEVELOPMENT_TEAM" ]; then + development_team="$DEVELOPMENT_TEAM" + else + teams="" + while IFS= read -r line; do + team_id=$(echo "$line" | grep -oE 'OU=[A-Z0-9]+' | cut -d= -f2) + cn=$(echo "$line" | grep -oE 'CN=[^,]+' | cut -d= -f2) + [ -n "$team_id" ] && teams=$(printf "%s\n%s|%s" "$teams" "$team_id" "$cn") + done <<< "$(security find-identity -v -p codesigning 2>/dev/null | grep "Apple Development" | sed 's/.*"\(.*\)".*/\1/' | while read name; do security find-certificate -c "$name" -p 2>/dev/null | openssl x509 -noout -subject 2>/dev/null; done | sort -u)" + teams=$(echo "$teams" | grep -v '^$') + + if [ -z "$teams" ]; then + echo "No Apple Development certificates found" + echo "Add one in Xcode > Settings > Accounts" + exit 1 + fi + + team_count=$(echo "$teams" | wc -l | tr -d ' ') + if [ "$team_count" -eq 1 ]; then + development_team=$(echo "$teams" | head -1 | cut -d'|' -f1) + else + echo "" + echo "Development Teams:" + team_num=0 + while IFS='|' read -r tid tname; do + team_num=$((team_num + 1)) + printf " %2d. %s (%s)\n" "$team_num" "$tname" "$tid" + done <<< "$teams" + echo "" + read -p "Select team (1-$team_num): " team_selection + if ! [[ "$team_selection" =~ ^[0-9]+$ ]] || [ "$team_selection" -lt 1 ] || [ "$team_selection" -gt "$team_num" ]; then + echo "Invalid selection" + exit 1 + fi + development_team=$(echo "$teams" | sed -n "${team_selection}p" | cut -d'|' -f1) + fi + fi + if [ -z "$development_team" ]; then + echo "Could not determine Team ID" + exit 1 + fi + echo "Using Team ID: $development_team" +fi + +if ! command -v ruby &>/dev/null; then + echo "Ruby not found" + exit 1 +fi + +if ! gem list xcodeproj -i &>/dev/null; then + echo "Installing xcodeproj gem..." + if ! gem install xcodeproj; then + echo "Failed to install xcodeproj gem" + exit 1 + fi +fi + +export PROJECT_ROOT TESTS_ROOT="$tests_root" XCODEPROJ_PATH="$xcodeproj_path" BUNDLE_ID="$bundle_id" DEVELOPMENT_TEAM="$development_team" DEVICE_TYPE="$device_type" CACTUS_CURL_ROOT="$CACTUS_CURL_ROOT" +if ! ruby "$SCRIPT_DIR/configure_xcode.rb"; then + echo "Failed to configure Xcode project" + exit 1 +fi + +echo "" +echo "Step 4: Building iOS test application..." + +if [ "$device_type" = "simulator" ]; then + ios_sim_sdk_path=$(xcrun --sdk iphonesimulator --show-sdk-path) + if [ -z "$ios_sim_sdk_path" ] || [ ! -d "$ios_sim_sdk_path" ]; then + echo "iOS Simulator SDK not found" + exit 1 + fi + + if ! xcodebuild -project "$xcodeproj_path" \ + -scheme CactusTest \ + -configuration Release \ + -destination "platform=iOS Simulator,id=$device_uuid" \ + -derivedDataPath "$SCRIPT_DIR/build" \ + ARCHS=arm64 \ + ONLY_ACTIVE_ARCH=NO \ + IPHONEOS_DEPLOYMENT_TARGET=13.0 \ + SDKROOT="$ios_sim_sdk_path" \ + PRODUCT_BUNDLE_IDENTIFIER="$bundle_id" \ + build; then + echo "Build failed" + exit 1 + fi + + app_path="$SCRIPT_DIR/build/Build/Products/Release-iphonesimulator/CactusTest.app" +else + ios_sdk_path=$(xcrun --sdk iphoneos --show-sdk-path) + if [ -z "$ios_sdk_path" ] || [ ! -d "$ios_sdk_path" ]; then + echo "iOS SDK not found" + exit 1 + fi + + if ! xcodebuild -project "$xcodeproj_path" \ + -scheme CactusTest \ + -configuration Release \ + -destination "platform=iOS,id=$device_uuid" \ + -derivedDataPath "$SCRIPT_DIR/build" \ + -allowProvisioningUpdates \ + ARCHS=arm64 \ + ONLY_ACTIVE_ARCH=NO \ + IPHONEOS_DEPLOYMENT_TARGET=13.0 \ + SDKROOT="$ios_sdk_path" \ + PRODUCT_BUNDLE_IDENTIFIER="$bundle_id" \ + CODE_SIGN_STYLE="Automatic" \ + build; then + echo "Build failed" + exit 1 + fi + + app_path="$SCRIPT_DIR/build/Build/Products/Release-iphoneos/CactusTest.app" +fi + +echo "" +echo "Step 5: Bundling model weights and assets..." + +model_src="$MODEL_NAME" +model_dir=$(basename "$model_src") +assets_src="$PROJECT_ROOT/cactus-engine/tests/assets" + +if [ ! -d "$model_src" ]; then + echo "Error: model weights not found at $model_src" + exit 1 +fi + +echo "Copying model weights to app bundle..." +rm -rf "$app_path/$model_dir" +if ! cp -R "$model_src" "$app_path/"; then + echo "Error: Could not copy model weights from $model_src" + exit 1 +fi + +if [ -d "$assets_src" ]; then + echo "Copying test assets to app bundle..." + rm -rf "$app_path/assets" + if ! cp -R "$assets_src" "$app_path/"; then + echo "Error: Could not copy test assets from $assets_src" + exit 1 + fi +fi + +echo "" +echo "Step 6: Running tests..." +echo "------------------------" + +if [ "$device_type" = "simulator" ]; then + echo "Installing on: $device_name" + + xcrun simctl boot "$device_uuid" || true + + if ! xcrun simctl install "$device_uuid" "$app_path"; then + echo "Failed to install app on simulator" + exit 1 + fi + + echo "Launching tests..." + echo "Using model path: $model_dir" + echo "Using assets path: assets" + + sim_env=( + "SIMCTL_CHILD_CACTUS_TEST_MODEL=$model_dir" + "SIMCTL_CHILD_CACTUS_TEST_ASSETS=assets" + "SIMCTL_CHILD_CACTUS_INDEX_PATH=assets" + "SIMCTL_CHILD_CACTUS_NO_CLOUD_TELE=${CACTUS_NO_CLOUD_TELE:-1}" + "SIMCTL_CHILD_CACTUS_TEST_ONLY=${CACTUS_TEST_ONLY:-}" + ) + + env "${sim_env[@]}" xcrun simctl launch --console-pty "$device_uuid" "$bundle_id" +else + echo "Installing on: $device_name" + + if ! xcrun devicectl device install app --device "$device_uuid" "$app_path"; then + echo "Failed to install app on device" + echo "Common issues:" + echo " - Device not trusted" + echo " - Code signing failed" + echo " - Device locked or screen off" + exit 1 + fi + + echo "Launching tests..." + echo "(Logs will be fetched from device after completion)" + echo "Using model path: $model_dir" + echo "Using assets path: assets" + + device_env=( + "DEVICECTL_CHILD_CACTUS_TEST_MODEL=$model_dir" + "DEVICECTL_CHILD_CACTUS_TEST_ASSETS=assets" + "DEVICECTL_CHILD_CACTUS_INDEX_PATH=assets" + "DEVICECTL_CHILD_CACTUS_NO_CLOUD_TELE=${CACTUS_NO_CLOUD_TELE:-1}" + "DEVICECTL_CHILD_CACTUS_TEST_ONLY=${CACTUS_TEST_ONLY:-}" + ) + + env "${device_env[@]}" \ + xcrun devicectl device process launch --device "$device_uuid" "$bundle_id" 2>&1 || true + + echo "Waiting for tests to complete..." + max_wait=300 + elapsed=0 + while [ $elapsed -lt $max_wait ]; do + if xcrun devicectl device info processes --device "$device_uuid" 2>/dev/null | grep -q "CactusTest.app/CactusTest"; then + sleep 2 + elapsed=$((elapsed + 2)) + else + break + fi + done + + if [ $elapsed -ge $max_wait ]; then + echo "Warning: Test execution timeout reached (${max_wait}s)" + fi + + sleep 1 + + echo "" + echo "Fetching logs from device..." + log_dir=$(mktemp -d) + xcrun devicectl device copy from --device "$device_uuid" \ + --domain-identifier "$bundle_id" \ + --domain-type appDataContainer \ + --source Documents/cactus_test.log \ + --destination "$log_dir/cactus_test.log" 2>/dev/null || true + + if [ -f "$log_dir/cactus_test.log" ]; then + echo "=== Device Test Output ===" + cat "$log_dir/cactus_test.log" + echo "=== End Device Test Output ===" + else + echo "Could not retrieve test logs from device" + fi + rm -rf "$log_dir" +fi + +echo "" +echo "Tests complete." diff --git a/cactus/cactus.h b/cactus/cactus.h index 7b032b6e2..ba649661c 100644 --- a/cactus/cactus.h +++ b/cactus/cactus.h @@ -4,6 +4,5 @@ #include "../cactus-kernels/cactus_kernels.h" #include "../cactus-graph/cactus_graph.h" #include "../cactus-engine/cactus_engine.h" -#include "../cactus-engine/src/engine.h" #endif // CACTUS_H diff --git a/llms.txt b/llms.txt index 2d45f63d9..d206be367 100644 --- a/llms.txt +++ b/llms.txt @@ -14,14 +14,14 @@ Supported models include Gemma 4 (E2B, E4B with vision + audio), Gemma 3/3n, Qwe - [Fine-tuning Guide](docs/finetuning.md): Deploying Unsloth LoRA fine-tunes to mobile devices via Cactus - [Compatibility](docs/compatibility.md): Runtime and weight versioning across releases -## SDKs - -- [Python](python/README.md): Python bindings via FFI with streaming, vision, audio, and graph API support -- [Swift](apple/README.md): Swift API for iOS, macOS, and Android with XCFramework and NPU support -- [Kotlin/Android](android/README.md): Kotlin API for Android and Kotlin Multiplatform (iOS + Android) -- [Flutter](flutter/README.md): Dart FFI bindings for iOS, macOS, and Android -- [Rust](rust/README.md): Raw FFI bindings auto-generated via bindgen -- [React Native](https://github.com/cactus-compute/cactus-react-native): React Native SDK (external repo) +## Bindings + +- [Python](python/README.md): Python bindings via ctypes FFI +- [Swift](bindings/swift/README.md): Swift bindings via C module map (iOS, macOS) +- [Kotlin](bindings/kotlin/README.md): Kotlin bindings via JNI (Android) and cinterop (iOS via KMP) +- [Flutter](bindings/flutter/README.md): Dart FFI bindings (iOS, Android) +- [Rust](bindings/rust/README.md): Raw `extern "C"` declarations +- [React Native](bindings/react-native/README.md): React Native bridge modules (iOS, Android) ## Blog diff --git a/python/README.md b/python/README.md index 7fe2500f9..dba156deb 100644 --- a/python/README.md +++ b/python/README.md @@ -1,7 +1,7 @@ --- -title: "Cactus Python SDK" -description: "Python bindings for Cactus on-device AI inference engine. Supports chat completion, vision, transcription, embeddings, RAG, tool calling, and streaming." -keywords: ["Python SDK", "on-device AI", "LLM inference", "Python FFI", "embeddings", "transcription", "RAG"] +title: "Cactus Python Package" +description: "Python package and ctypes bindings for the Cactus on-device AI inference engine." +keywords: ["Python package", "Python bindings", "on-device AI", "Python FFI", "embeddings", "transcription", "RAG"] --- # Cactus Python Package @@ -326,7 +326,7 @@ Returns a JSON string with a `chunks` array. Each chunk has `score` (float), `so ```python index = cactus_index_init(index_dir: str, embedding_dim: int) -> int cactus_index_add(index: int, ids: list[int], documents: list[str], - embeddings: list[list[float]], metadatas: list[str] | None) + metadatas: list[str] | None, embeddings: list[list[float]]) cactus_index_delete(index: int, ids: list[int]) result_json = cactus_index_get(index: int, ids: list[int]) -> str result_json = cactus_index_query(index: int, embedding: list[float], options_json: str | None) -> str @@ -429,10 +429,13 @@ Tests are in `python/tests/`: ## See Also -- [Cactus Engine API](/docs/cactus_engine.md) — Full C API reference that the Python bindings wrap -- [Cactus Index API](/docs/cactus_index.md) — Vector database API for RAG applications -- [Fine-tuning Guide](/docs/finetuning.md) — Train and deploy custom LoRA fine-tunes -- [Runtime Compatibility](/docs/compatibility.md) — Weight versioning across releases -- [Swift SDK](/apple/) — Swift bindings for iOS/macOS -- [Kotlin/Android SDK](/android/) — Kotlin bindings for Android -- [Flutter SDK](/flutter/) — Dart bindings for cross-platform mobile +- `Cactus Engine API` — Full C API reference that the Python bindings wrap +- `Cactus Index API` — Vector database API for RAG applications +- `Fine-tuning Guide` — Train and deploy custom LoRA fine-tunes +- `Runtime Compatibility` — Weight versioning across releases +- [Apple Build Step](/apple/) — Builds Apple native artifacts used by bindings +- [Android Build Step](/android/) — Builds Android native artifacts used by bindings +- [Swift Bindings](/bindings/swift/) — Swift C-module bindings +- [Kotlin Bindings](/bindings/kotlin/) — Kotlin/JNI bindings +- [Flutter Bindings](/bindings/flutter/) — Dart FFI bindings +- [Rust Bindings](/bindings/rust/) — Raw Rust FFI declarations diff --git a/python/cactus/__init__.py b/python/cactus/__init__.py index 3aa593c6b..8316bc618 100644 --- a/python/cactus/__init__.py +++ b/python/cactus/__init__.py @@ -21,6 +21,13 @@ def __getattr__(name): "cactus_embed", "cactus_image_embed", "cactus_audio_embed", "cactus_transcribe", "cactus_detect_language", "cactus_vad", "cactus_diarize", "cactus_embed_speaker", + "cactus_tokenize", "cactus_score_window", "cactus_rag_query", + "cactus_get_last_error", "cactus_log_set_level", "cactus_log_set_callback", + "cactus_set_telemetry_environment", "cactus_set_app_id", + "cactus_telemetry_flush", "cactus_telemetry_shutdown", + "cactus_index_init", "cactus_index_add", "cactus_index_delete", + "cactus_index_get", "cactus_index_query", "cactus_index_compact", + "cactus_index_destroy", } if name in _ffi_names: from .bindings import cactus diff --git a/python/cactus/bindings/cactus.py b/python/cactus/bindings/cactus.py index e3929275b..5ca7a0fb5 100644 --- a/python/cactus/bindings/cactus.py +++ b/python/cactus/bindings/cactus.py @@ -803,7 +803,7 @@ def _enc(s): def cactus_get_last_error(): - """Returns the last error message or None.""" + """Returns the last error message, or None if no error.""" result = _lib.cactus_get_last_error() return result.decode() if result else None @@ -812,9 +812,9 @@ def _err(default): return cactus_get_last_error() or default -def cactus_set_telemetry_environment(cache_location): - """Sets the telemetry cache directory.""" - _lib.cactus_set_telemetry_environment(None, _enc(cache_location), None) +def cactus_set_telemetry_environment(framework, cache_location, version): + """Sets telemetry environment (framework name, cache path, version).""" + _lib.cactus_set_telemetry_environment(_enc(framework), _enc(cache_location), _enc(version)) def cactus_set_app_id(app_id): @@ -828,12 +828,12 @@ def cactus_telemetry_flush(): def cactus_telemetry_shutdown(): - """Flushes and shuts down the telemetry subsystem.""" + """Shuts down the telemetry subsystem.""" _lib.cactus_telemetry_shutdown() def cactus_init(model_path, corpus_dir, cache_index): - """Initializes a model from the given path. Returns handle.""" + """Loads a model from the given path. Returns an opaque model handle.""" handle = _lib.cactus_init(_enc(model_path), _enc(corpus_dir), cache_index) if not handle: raise RuntimeError(_err("Failed to initialize model")) @@ -841,22 +841,22 @@ def cactus_init(model_path, corpus_dir, cache_index): def cactus_destroy(model): - """Frees all model resources.""" + """Frees all resources associated with the model handle.""" _lib.cactus_destroy(model) def cactus_reset(model): - """Clears the KV cache.""" + """Clears the KV cache, resetting the model to a fresh state.""" _lib.cactus_reset(model) def cactus_stop(model): - """Signals the current generation to stop.""" + """Signals the model to stop the current generation.""" _lib.cactus_stop(model) def cactus_complete(model, messages_json, options_json, tools_json, callback, pcm_data=None): - """Runs chat completion. Returns response string.""" + """Runs chat completion. Returns a JSON string with the response and metrics.""" buf = ctypes.create_string_buffer(65536) if callback: def _bridge(token_bytes, token_id, _): @@ -881,7 +881,7 @@ def _bridge(token_bytes, token_id, _): def cactus_prefill(model, messages_json, options_json, tools_json, pcm_data=None): - """Prefills the KV cache with messages.""" + """Pre-fills the KV cache with the given messages. Returns a JSON string with prefill stats.""" buf = ctypes.create_string_buffer(65536) if pcm_data is not None: pcm_arr = (ctypes.c_uint8 * len(pcm_data))(*pcm_data) @@ -896,8 +896,10 @@ def cactus_prefill(model, messages_json, options_json, tools_json, pcm_data=None ) if rc < 0: raise RuntimeError(_err("Prefill failed")) + return buf.value.decode("utf-8", errors="replace") + def cactus_detect_language(model, audio_path, options_json, pcm_data): - """Detects the spoken language in audio. Returns JSON string.""" + """Detects the spoken language in audio. Returns a JSON string.""" buf = ctypes.create_string_buffer(65536) if pcm_data is not None: pcm_arr = (ctypes.c_uint8 * len(pcm_data))(*pcm_data) @@ -915,7 +917,7 @@ def cactus_detect_language(model, audio_path, options_json, pcm_data): def cactus_transcribe(model, audio_path, prompt, options_json, callback, pcm_data): - """Transcribes audio to text. Returns transcription string.""" + """Transcribes audio to text. Returns a JSON string with transcription and segments.""" buf = ctypes.create_string_buffer(65536) if callback: def _bridge(token_bytes, token_id, _): @@ -940,7 +942,7 @@ def _bridge(token_bytes, token_id, _): def cactus_embed(model, text, normalize): - """Generates a text embedding. Returns list of floats.""" + """Computes a text embedding. Returns a list of floats.""" buf = (ctypes.c_float * 4096)() dim = ctypes.c_size_t() rc = _lib.cactus_embed(model, _enc(text), buf, 4096, ctypes.byref(dim), normalize) @@ -950,7 +952,7 @@ def cactus_embed(model, text, normalize): def cactus_image_embed(model, image_path): - """Generates an image embedding. Returns list of floats.""" + """Computes an image embedding. Returns a list of floats.""" buf = (ctypes.c_float * 4096)() dim = ctypes.c_size_t() rc = _lib.cactus_image_embed(model, _enc(image_path), buf, 4096, ctypes.byref(dim)) @@ -960,7 +962,7 @@ def cactus_image_embed(model, image_path): def cactus_audio_embed(model, audio_path): - """Generates an audio embedding. Returns list of floats.""" + """Computes an audio embedding. Returns a list of floats.""" buf = (ctypes.c_float * 4096)() dim = ctypes.c_size_t() rc = _lib.cactus_audio_embed(model, _enc(audio_path), buf, 4096, ctypes.byref(dim)) @@ -970,7 +972,7 @@ def cactus_audio_embed(model, audio_path): def cactus_preprocess_audio_features(audio_path, model_type, mel_bins, capacity): - """Returns Cactus-native audio frontend features as (values, mel_bins, frames).""" + """Computes mel spectrogram features. Returns (values, mel_bins, frames).""" if not hasattr(_lib, "cactus_preprocess_audio_features"): raise RuntimeError("cactus_preprocess_audio_features is unavailable; rebuild with cactus build --python") buf = (ctypes.c_float * int(capacity))() @@ -993,7 +995,7 @@ def cactus_preprocess_audio_features(audio_path, model_type, mel_bins, capacity) def cactus_vad(model, audio_path, options_json, pcm_data): - """Runs voice activity detection. Returns JSON string.""" + """Runs voice activity detection. Returns a JSON string with speech segments.""" buf = ctypes.create_string_buffer(65536) if pcm_data is not None: pcm_arr = (ctypes.c_uint8 * len(pcm_data))(*pcm_data) @@ -1011,7 +1013,7 @@ def cactus_vad(model, audio_path, options_json, pcm_data): def cactus_diarize(model, audio_path, options_json, pcm_data): - """Runs speaker diarization. Returns JSON string.""" + """Runs speaker diarization. Returns a JSON string with per-speaker segments.""" buf = ctypes.create_string_buffer(1 << 20) if pcm_data is not None: pcm_arr = (ctypes.c_uint8 * len(pcm_data))(*pcm_data) @@ -1029,7 +1031,7 @@ def cactus_diarize(model, audio_path, options_json, pcm_data): def cactus_embed_speaker(model, audio_path, options_json, pcm_data, mask_weights=None): - """Extracts a speaker embedding vector. Returns JSON string.""" + """Extracts a speaker embedding. Returns a JSON string.""" buf = ctypes.create_string_buffer(65536) if pcm_data is not None: pcm_arr = (ctypes.c_uint8 * len(pcm_data))(*pcm_data) @@ -1055,7 +1057,7 @@ def cactus_embed_speaker(model, audio_path, options_json, pcm_data, mask_weights def cactus_tokenize(model, text): - """Tokenizes text into token IDs. Returns list of ints.""" + """Tokenizes text into token IDs. Returns a list of ints.""" max_tokens = 8192 arr = (ctypes.c_uint32 * max_tokens)() n = ctypes.c_size_t(0) @@ -1066,7 +1068,7 @@ def cactus_tokenize(model, text): def cactus_decode_tokens(model, tokens, temperature=0.0, top_p=1.0, top_k=1): - """Returns the next token ID from native Cactus for exact raw token IDs.""" + """Decodes the next token from a sequence. Returns the next token ID.""" if not tokens: raise ValueError("tokens must be non-empty") arr = (ctypes.c_uint32 * len(tokens))(*[int(token) for token in tokens]) @@ -1086,7 +1088,7 @@ def cactus_decode_tokens(model, tokens, temperature=0.0, top_p=1.0, top_k=1): def cactus_score_window(model, tokens, start, end, context): - """Scores a window of tokens. Returns JSON string.""" + """Scores a window of tokens. Returns a JSON string with log-probabilities.""" buf = ctypes.create_string_buffer(65536) token_len = len(tokens) arr = (ctypes.c_uint32 * token_len)(*tokens) @@ -1097,7 +1099,7 @@ def cactus_score_window(model, tokens, start, end, context): def cactus_rag_query(model, query, top_k): - """Queries the RAG corpus. Returns JSON string.""" + """Queries the RAG corpus. Returns a JSON string with results.""" buf = ctypes.create_string_buffer(65536) rc = _lib.cactus_rag_query(model, _enc(query), buf, len(buf), top_k) if rc < 0: @@ -1106,7 +1108,7 @@ def cactus_rag_query(model, query, top_k): def cactus_stream_transcribe_start(model, options_json): - """Creates a streaming transcription session. Returns stream handle.""" + """Starts a streaming transcription session. Returns a stream handle.""" handle = _lib.cactus_stream_transcribe_start(model, _enc(options_json)) if not handle: raise RuntimeError(_err("Failed to start stream transcription")) @@ -1114,7 +1116,7 @@ def cactus_stream_transcribe_start(model, options_json): def cactus_stream_transcribe_process(stream, pcm_data): - """Processes a chunk of PCM audio. Returns partial text.""" + """Feeds a PCM audio chunk to the stream. Returns partial transcription.""" buf = ctypes.create_string_buffer(65536) pcm_arr = (ctypes.c_uint8 * len(pcm_data))(*pcm_data) pcm_ptr = ctypes.cast(pcm_arr, ctypes.POINTER(ctypes.c_uint8)) @@ -1125,7 +1127,7 @@ def cactus_stream_transcribe_process(stream, pcm_data): def cactus_stream_transcribe_stop(stream): - """Finalizes transcription. Returns final text.""" + """Finalizes streaming transcription. Returns the final transcription.""" buf = ctypes.create_string_buffer(65536) rc = _lib.cactus_stream_transcribe_stop(stream, buf, len(buf)) if rc < 0: @@ -1134,14 +1136,14 @@ def cactus_stream_transcribe_stop(stream): def cactus_index_init(index_dir, embedding_dim): - """Initializes a vector index in the given directory. Returns handle.""" + """Creates a vector index. Returns an opaque index handle.""" handle = _lib.cactus_index_init(_enc(index_dir), embedding_dim) if not handle: raise RuntimeError(_err("Failed to initialize index")) return handle -def cactus_index_add(index, ids, documents, embeddings, metadatas): +def cactus_index_add(index, ids, documents, metadatas, embeddings): """Adds documents with embeddings to the index.""" count = len(ids) embedding_dim = len(embeddings[0]) if embeddings else 0 @@ -1171,7 +1173,7 @@ def cactus_index_add(index, ids, documents, embeddings, metadatas): def cactus_index_delete(index, ids): - """Removes documents by ID.""" + """Removes documents from the index by ID.""" count = len(ids) ids_arr = (ctypes.c_int * count)(*ids) rc = _lib.cactus_index_delete(index, ids_arr, count) @@ -1180,25 +1182,22 @@ def cactus_index_delete(index, ids): def cactus_index_query(index, embedding, options_json): - """Searches the index by embedding. Returns JSON string.""" + """Queries the index by embedding. Returns a JSON string with ids and scores.""" result_capacity = 1000 embedding_dim = len(embedding) emb_arr = (ctypes.c_float * embedding_dim)(*embedding) emb_ptr = ctypes.cast(emb_arr, ctypes.POINTER(ctypes.c_float)) emb_ptr_ptr = ctypes.pointer(emb_ptr) - id_buffer = (ctypes.c_int * result_capacity)() score_buffer = (ctypes.c_float * result_capacity)() id_ptr = ctypes.cast(id_buffer, ctypes.POINTER(ctypes.c_int)) score_ptr = ctypes.cast(score_buffer, ctypes.POINTER(ctypes.c_float)) id_size = ctypes.c_size_t(result_capacity) score_size = ctypes.c_size_t(result_capacity) - id_ptr_ptr = ctypes.pointer(id_ptr) - score_ptr_ptr = ctypes.pointer(score_ptr) - rc = _lib.cactus_index_query( - index, emb_ptr_ptr, 1, embedding_dim, _enc(options_json), - id_ptr_ptr, ctypes.byref(id_size), score_ptr_ptr, ctypes.byref(score_size) + index, ctypes.pointer(emb_ptr), 1, embedding_dim, _enc(options_json), + ctypes.pointer(id_ptr), ctypes.byref(id_size), + ctypes.pointer(score_ptr), ctypes.byref(score_size) ) if rc < 0: raise RuntimeError(_err("Index query failed")) @@ -1212,25 +1211,18 @@ def cactus_index_query(index, embedding, options_json): def cactus_index_get(index, ids): - """Retrieves documents by ID. Returns JSON string.""" + """Retrieves documents by ID. Returns a JSON string with documents, metadata, and embeddings.""" count = len(ids) - if count == 0: - return '{"results":[]}' - ids_arr = (ctypes.c_int * count)(*ids) - doc_raw = [ctypes.create_string_buffer(_INDEX_DOC_BUF_SIZE) for _ in range(count)] doc_ptrs = (ctypes.c_char_p * count)() doc_sizes = (ctypes.c_size_t * count)() - meta_raw = [ctypes.create_string_buffer(_INDEX_DOC_BUF_SIZE) for _ in range(count)] meta_ptrs = (ctypes.c_char_p * count)() meta_sizes = (ctypes.c_size_t * count)() - emb_raw = [(ctypes.c_float * _INDEX_EMB_BUF_SIZE)() for _ in range(count)] emb_ptrs = (ctypes.POINTER(ctypes.c_float) * count)() emb_sizes = (ctypes.c_size_t * count)() - for i in range(count): doc_ptrs[i] = ctypes.cast(doc_raw[i], ctypes.c_char_p) doc_sizes[i] = _INDEX_DOC_BUF_SIZE @@ -1238,41 +1230,37 @@ def cactus_index_get(index, ids): meta_sizes[i] = _INDEX_DOC_BUF_SIZE emb_ptrs[i] = ctypes.cast(emb_raw[i], ctypes.POINTER(ctypes.c_float)) emb_sizes[i] = _INDEX_EMB_BUF_SIZE - rc = _lib.cactus_index_get( index, ids_arr, count, doc_ptrs, doc_sizes, meta_ptrs, meta_sizes, emb_ptrs, emb_sizes ) if rc < 0: raise RuntimeError(_err("Failed to get from index")) - parts = [] for i in range(count): doc = doc_raw[i].value.decode("utf-8", errors="ignore") - meta_bytes = meta_raw[i].value - meta = meta_bytes.decode("utf-8", errors="ignore") if meta_bytes else None - emb_dim = emb_sizes[i] - emb = list(emb_raw[i][:emb_dim]) if emb_dim > 0 else [] - meta_str = f'"{meta}"' if meta is not None else "null" + meta = meta_raw[i].value.decode("utf-8", errors="ignore") + emb = list(emb_raw[i][:emb_sizes[i]]) + meta_str = f'"{meta}"' if meta else "null" emb_str = "[" + ",".join(str(v) for v in emb) + "]" parts.append(f'{{"document":"{doc}","metadata":{meta_str},"embedding":{emb_str}}}') return '{"results":[' + ",".join(parts) + ']}' def cactus_index_compact(index): - """Compacts the index storage.""" + """Compacts the index storage on disk.""" rc = _lib.cactus_index_compact(index) if rc < 0: raise RuntimeError(_err("Failed to compact index")) def cactus_index_destroy(index): - """Frees all index resources.""" + """Frees all resources associated with the index handle.""" _lib.cactus_index_destroy(index) def cactus_log_set_level(level): - """Sets the log level. 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=NONE.""" + """Sets the log level: 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=NONE.""" _lib.cactus_log_set_level(level) @@ -1280,7 +1268,7 @@ def cactus_log_set_level(level): def cactus_log_set_callback(callback): - """Sets a log callback. Pass None to clear. Callback signature: (level: int, component: str, message: str).""" + """Sets a log callback: callback(level, component, message). Pass None to clear.""" global _log_callback_ref if callback is None: _log_callback_ref = None diff --git a/python/cactus/cli/__init__.py b/python/cactus/cli/__init__.py index 44016afb6..b55de430a 100644 --- a/python/cactus/cli/__init__.py +++ b/python/cactus/cli/__init__.py @@ -93,7 +93,6 @@ def create_parser(): Optional flags: --apple build for Apple (iOS/macOS) --android build for Android - --flutter build for Flutter (all platforms) --python build shared lib for Python FFI ----------------------------------------------------------------- @@ -107,7 +106,6 @@ def create_parser(): --whisper_model default: openai/whisper-small (language detection) --benchmark use larger models (LFM2.5-VL-1.6B + nvidia/parakeet-ctc-1.1b) --reconvert force model weights reconversion from source - --no-rebuild skip building library and tests --llm run only LLM tests --vlm run only VLM tests --stt run only speech-to-text tests @@ -179,8 +177,6 @@ def create_parser(): help='Build for Apple platforms (iOS/macOS)') build_parser.add_argument('--android', action='store_true', help='Build for Android') - build_parser.add_argument('--flutter', action='store_true', - help='Build for Flutter (iOS, macOS, Android)') build_parser.add_argument('--python', action='store_true', help='Build shared library for Python FFI') @@ -258,8 +254,6 @@ def create_parser(): test_parser = subparsers.add_parser('test', help='Run the test suite') test_parser.add_argument('--model', default=DEFAULT_TEST_MODEL_ID, help='Model to use for tests (default: Gemma4)') - test_parser.add_argument('--no-rebuild', action='store_true', - help='Skip building cactus library and tests') test_parser.add_argument('--token', help='HuggingFace API token') test_parser.add_argument('--android', action='store_true', help='Run tests on Android') diff --git a/python/cactus/cli/download.py b/python/cactus/cli/download.py index 353fdfb9d..08d50141b 100644 --- a/python/cactus/cli/download.py +++ b/python/cactus/cli/download.py @@ -1,7 +1,7 @@ """CQ archive discovery and download helpers. The resolver in this module is deliberately independent of argparse and the -rest of the CLI. Keep this logic small and data-shaped so other SDKs can port +rest of the CLI. Keep this logic small and data-shaped so other bindings can port the same model/repo/combo behavior without inheriting Python CLI details. """ from __future__ import annotations diff --git a/python/cactus/cli/misc.py b/python/cactus/cli/misc.py index 33c54f299..23c60580c 100644 --- a/python/cactus/cli/misc.py +++ b/python/cactus/cli/misc.py @@ -91,7 +91,7 @@ def remove_if_exists(path): print("Removing compiled libraries and frameworks...") preserve_roots = [ - PROJECT_ROOT / "libs" / "curl", + PROJECT_ROOT / "cactus-engine" / "libs" / "curl", PROJECT_ROOT / "android" / "mbedtls", PROJECT_ROOT / "libs" / "mbedtls", ] diff --git a/python/cactus/cli/test.py b/python/cactus/cli/test.py index 7a19bcfea..711afd17d 100644 --- a/python/cactus/cli/test.py +++ b/python/cactus/cli/test.py @@ -4,6 +4,7 @@ from .common import ( PROJECT_ROOT, DEFAULT_TEST_MODEL_ID, + get_weights_dir, print_color, RED, YELLOW, BLUE, ) @@ -15,6 +16,8 @@ def cmd_test(args): print_color(BLUE, "Running test suite...") print("=" * 20) + model_id = getattr(args, 'model', DEFAULT_TEST_MODEL_ID) + if getattr(args, 'ios', False) and not getattr(args, 'reconvert', False): print_color( YELLOW, @@ -22,20 +25,18 @@ def cmd_test(args): "If tests fail unexpectedly, rerun with --reconvert." ) - if getattr(args, 'reconvert', False): - model_id = getattr(args, 'model', DEFAULT_TEST_MODEL_ID) - class DownloadArgs: - pass - dl_args = DownloadArgs() - dl_args.model_id = model_id - dl_args.reconvert = True - dl_args.cache_dir = None - if args.token: - dl_args.token = args.token - if cmd_download(dl_args) != 0: - return 1 + from types import SimpleNamespace + dl_args = SimpleNamespace( + model_id=model_id, + reconvert=getattr(args, 'reconvert', False), + cache_dir=None, + token=getattr(args, 'token', None), + ) + if cmd_download(dl_args) != 0: + print_color(RED, "Failed to download model weights") + return 1 - test_filter = args.only + test_filter = getattr(args, 'only', None) for _test_name in ['llm', 'vlm', 'stt', 'embed', 'rag', 'graph', 'index', 'kernel', 'kv_cache', 'performance']: if getattr(args, _test_name, False): test_filter = _test_name @@ -57,10 +58,9 @@ class DownloadArgs: cmd = [str(test_script)] - if args.model: - cmd.extend(["--model", args.model]) - if getattr(args, 'no_rebuild', False): - cmd.append("--no-rebuild") + weights_dir = get_weights_dir(model_id) + cmd.extend(["--model", str(weights_dir)]) + if args.android: cmd.append("--android") if args.ios: