Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 29 additions & 24 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -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
ruy
34 changes: 23 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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 │
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
217 changes: 45 additions & 172 deletions android/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -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 $<TARGET_FILE:cactus_engine>
addlib $<TARGET_FILE:cactus_graph>
addlib $<TARGET_FILE:cactus_kernels>
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)
Loading
Loading