cactus-react-native 0.2.11 → 1.0.1

package/Cactus.podspec

@@ -0,0 +1,34 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "Cactus"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/cactus-compute/cactus-react-native.git", :tag => "#{s.version}" }
+
+
+  s.source_files = [
+    "ios/**/*.{swift}",
+    "ios/**/*.{m,mm}",
+    "cpp/**/*.{h,hpp,cpp}",
+  ]
+
+  s.vendored_frameworks = ["ios/cactus.xcframework", "ios/cactus_util.xcframework"]
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+ 
+  s.dependency 'ZIPFoundation', '~> 0.9'
+
+  load 'nitrogen/generated/ios/Cactus+autolinking.rb'
+  add_nitrogen_files(s)
+
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -0,0 +1,38 @@
+Copyright (c) 2025 Cactus Compute, Inc. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, merge, publish, and distribute the Software, and to permit 
+persons to whom the Software is furnished to do so, subject to the following 
+conditions:
+
+1. The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+2. This grant of permission applies only to:
+   (a) Individual persons using the Software for personal, educational, 
+       research, or non-commercial purposes;
+   (b) Organizations (including their parent companies and subsidiaries) with both:
+       (i) Less than $2,000,000 USD in total funding (including but not limited to
+           equity investments, debt financing, grants, and loans); AND
+       (ii) Less than $2,000,000 USD in gross annual revenue;
+   (c) Educational institutions and students;
+   (d) Non-profit organizations registered under section 501(c)(3) of the 
+       United States Internal Revenue Code or equivalent in other jurisdictions.
+
+3. Any person or organization not meeting the criteria in Section 2 must obtain
+   a separate commercial license from Cactus Compute, Inc. Contact 
+   founders@cactuscompute.com for licensing terms.
+
+4. If an organization qualifying under Section 2(b) subsequently exceeds either
+   threshold, this permission automatically terminates and a commercial license
+   must be obtained within thirty (30) days. For purposes of this license,
+   "gross annual revenue" means total revenue in the preceding 12 months.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,104 +1,389 @@
 ![Cactus Logo](assets/logo.png)
 
-Official React-Native plugin for Cactus, a framework for deploying LLM/VLM/TTS models locally in your app. Requires iOS 12.0+, Android API 24+ and Yarn. For iOS apps, ensure you have cocoapods or install with `brew install cocoapods`. For Android apps, you need Java 17 installed. Expo is strongly recommended.
-
 ## Resources
+
 [![cactus](https://img.shields.io/badge/cactus-000000?logo=github&logoColor=white)](https://github.com/cactus-compute/cactus) [![HuggingFace](https://img.shields.io/badge/HuggingFace-FFD21E?logo=huggingface&logoColor=black)](https://huggingface.co/Cactus-Compute/models?sort=downloads) [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/bNurx3AXTJ) [![Documentation](https://img.shields.io/badge/Documentation-4285F4?logo=googledocs&logoColor=white)](https://cactuscompute.com/docs/react-native)
 
 ## Installation
-Execute the following command in your project terminal:
+
 ```bash
-npm install cactus-react-native 
-# or 
-yarn add cactus-react-native
+npm install cactus-react-native react-native-nitro-modules
 ```
-*N/B*: To build locally or use this repo, see instructions in `example/README.md`
 
-## Text Completion
+## Language Model
+
+### Completion
+
+#### Class
+
 ```typescript
-import { CactusLM } from 'cactus-react-native';
+import { CactusLM, type Message } from 'cactus-react-native';
+
+const cactusLM = new CactusLM();
+
+const messages: Message[] = [{ role: 'user', content: 'Hello, World!' }];
+const onToken = (token: string) => {
+  console.log('Received token:', token);
+};
+
+const result = await cactusLM.complete({ messages, onToken });
+console.log('Completion result:', result);
+```
+
+#### Hook
+
+```tsx
+import { useCactusLM, type Message } from 'cactus-react-native';
+
+const App = () => {
+  const cactusLM = useCactusLM();
+
+  const handleComplete = async () => {
+    const messages: Message[] = [{ role: 'user', content: 'Hello, World!' }];
+
+    const result = await cactusLM.complete({ messages });
+    console.log('Completion result:', result);
+  };
+
+  return (
+    <>
+      <Button title="Complete" onPress={handleComplete} />
+      <Text>{cactusLM.completion}</Text>
+    </>
+  );
+};
+```
+
+### Tool Calling
+
+#### Class
+
+```typescript
+import { CactusLM, type Message, type Tool } from 'cactus-react-native';
+
+const tools: Tool[] = [
+  {
+    type: 'function',
+    name: 'get_weather',
+    description: 'Get current weather for a location',
+    parameters: {
+      type: 'object',
+      properties: {
+        location: {
+          type: 'string',
+          description: 'City name',
+        },
+      },
+      required: ['location'],
+    },
+  },
+];
+
+const cactusLM = new CactusLM();
+
+const messages: Message[] = [
+  { role: 'user', content: "What's the weather in San Francisco?" },
+];
+
+const result = await cactusLM.complete({ messages, tools });
+console.log('Response:', result.response);
+```
+
+#### Hook
+
+```typescript
+import { useCactusLM, type Message, type Tool } from 'cactus-react-native';
+
+const tools: Tool[] = [
+  {
+    type: 'function',
+    name: 'get_weather',
+    description: 'Get current weather for a location',
+    parameters: {
+      type: 'object',
+      properties: {
+        location: {
+          type: 'string',
+          description: 'City name',
+        },
+      },
+      required: ['location'],
+    },
+  },
+];
+
+const App = () => {
+  const cactusLM = useCactusLM();
+
+  const handleComplete = async () => {
+    const messages: Message[] = [
+      { role: 'user', content: "What's the weather in San Francisco?" },
+    ];
 
-const { lm, error } = await CactusLM.init({
-    model: '/path/to/model.gguf', // this is a local model file inside the app sandbox
-    n_ctx: 2048,
-});
+    const result = await cactusLM.complete({ messages, tools });
+    console.log('Response:', result.response);
+    console.log('Function calls:', result.functionCalls);
+  };
 
-const messages = [{ role: 'user', content: 'Hello!' }];
-const params = { n_predict: 100, temperature: 0.7 };
-const response = await lm.completion(messages, params);
+  return <Button title="Complete" onPress={handleComplete} />;
+};
 ```
-## Embeddings
- ```typescript
+
+### Embedding
+
+#### Class
+
+```typescript
 import { CactusLM } from 'cactus-react-native';
 
-const { lm, error } = await CactusLM.init({
-    model: '/path/to/model.gguf', // local model file inside the app sandbox
-    n_ctx: 2048,
-    embedding: true,
-});
+const cactusLM = new CactusLM();
 
-const text = 'Your text to embed';
-const params = { normalize: true };
-const result = await lm.embedding(text, params);
+const result = await cactusLM.embed({ text: 'Hello, World!' });
+console.log('Embedding vector:', result.embedding);
+console.log('Embedding vector length:', result.embedding.length);
 ```
-## Visual Language Models
+
+#### Hook
+
 ```typescript
-import { CactusVLM } from 'cactus-react-native';
+import { useCactusLM } from 'cactus-react-native';
 
-const { vlm, error } = await CactusVLM.init({
-    model: '/path/to/vision-model.gguf', // local model file inside the app sandbox
-    mmproj: '/path/to/mmproj.gguf', // local model file inside the app sandbox
-});
+const App = () => {
+  const cactusLM = useCactusLM();
 
-const messages = [{ role: 'user', content: 'Describe this image' }];
+  const handleEmbed = async () => {
+    const result = await cactusLM.embed({ text: 'Hello, World!' });
+    console.log('Embedding vector:', result.embedding);
+    console.log('Embedding vector length:', result.embedding.length);
+  };
 
-const params = {
-    images: ['/absolute/path/to/image.jpg'],
-    n_predict: 200,
-    temperature: 0.3,
+  return <Button title="Embed" onPress={handleEmbed} />;
 };
+```
+
+## API Reference
+
+### `CactusLM` Class
+
+#### Constructor
+
+**`new CactusLM(params?: CactusLMParams)`**
+
+- `model` - Model slug (default: `'qwen3-0.6'`)
+- `contextSize` - Context window size (default: `2048`)
+
+#### Methods
+
+**`download(params?: CactusLMDownloadParams): Promise<void>`**
+
+- Downloads the model.
+- `onProgress` - Callback for download progress (0-1).
+
+**`init(): Promise<void>`**
+
+- Initializes the model and prepares it for inference.
+
+**`complete(params: CactusLMCompleteParams): Promise<CactusLMCompleteResult>`**
+
+- Performs text completion with optional streaming and tool support (initializes the model if needed).
+- `messages` - Array of `Message` objects.
+- `options` - Generation options:
+
+  - `temperature` - Sampling temperature (default: model-optimized).
+  - `topP` - Nucleus sampling threshold (default: model-optimized).
+  - `topK` - Top-K sampling limit (default: model-optimized).
+  - `maxTokens` - Maximum number of tokens to generate (default: `512`).
+  - `stopSequences` - Array of strings to stop generation (default: `undefined`).
+- `tools` - Array of `Tool` objects for function calling (default: `undefined`).
+- `onToken` - Callback for streaming tokens.
 
-const response = await vlm.completion(messages, params);
+**`embed(params: CactusLMEmbedParams): Promise<CactusLMEmbedResult>`**
+
+- Generates embeddings for the given text (initializes the model if needed).
+- `text` - Text to embed.
+
+**`stop(): Promise<void>`**
+
+- Stops ongoing generation.
+
+**`reset(): Promise<void>`**
+
+- Resets the model's internal state, clearing any cached context.
+
+**`destroy(): Promise<void>`**
+
+- Releases all resources associated with the model.
+
+**`getModels(params?: CactusLMGetModelsParams): Promise<CactusModel[]>`**
+
+- Fetches available models and persists the results locally.
+- `forceRefresh` - If `true`, forces a fetch from the server and updates the local data (default: `false`).
+
+### `useCactusLM` Hook
+
+#### State
+
+- `completion: string` - Current generated text.
+- `isGenerating: boolean` - Whether the model is currently generating.
+- `isInitializing: boolean` - Whether the model is initializing.
+- `isDownloaded: boolean` - Whether the model is downloaded locally.
+- `isDownloading: boolean` - Whether the model is being downloaded.
+- `downloadProgress: number` - Download progress (0-1). `0` if not downloading.
+- `error: string | null` - Last error message, or `null` if there is no error.
+
+#### Methods
+
+- `download(params?: CactusLMDownloadParams): Promise<void>`
+- `init(): Promise<void>`
+- `complete(params: CactusLMCompleteParams): Promise<CactusLMCompleteResult>`
+- `embed(params: CactusLMEmbedParams): Promise<CactusLMEmbedResult>`
+- `stop(): Promise<void>`
+- `reset(): Promise<void>`
+- `destroy(): Promise<void>`
+- `getModels(params?: CactusLMGetModelsParams): Promise<CactusModel[]>`
+
+## Type Definitions
+
+### `CactusLMParams`
+
+```typescript
+interface CactusLMParams {
+  model?: string;
+  contextSize?: number;
+}
+```
+
+### `CactusLMDownloadParams`
+
+```typescript
+interface CactusLMDownloadParams {
+  onProgress?: (progress: number) => void;
+}
 ```
-## Cloud Fallback
+
+### `Message`
+
 ```typescript
-const { lm } = await CactusLM.init({
-  model: '/path/to/model.gguf',
-  n_ctx: 2048,
-}, undefined, 'your_cactus_token');
+interface Message {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+```
 
-// Try local first, fallback to cloud if local fails (its blazing fast)
-const embedding = await lm.embedding('text', undefined, 'localfirst');
+### `Options`
 
-// local (default): strictly only run on-device
-// localfirst: fallback to cloud if device fails
-// remotefirst: primarily remote, run local if API fails
-// remote: strictly run on cloud
+```typescript
+interface Options {
+  temperature?: number;
+  topP?: number;
+  topK?: number;
+  maxTokens?: number;
+  stopSequences?: string[];
+}
 ```
 
-## Agents
+### `Tool`
+
 ```typescript
-import { CactusAgent } from 'cactus-react-native';
+interface Tool {
+  type: 'function';
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: {
+      [key: string]: {
+        type: string;
+        description: string;
+      };
+    };
+    required: string[];
+  };
+}
+```
 
-// we recommend Qwen 3 family, 0.6B is great
-const { agent, error } = await CactusAgent.init({
-    model: '/path/to/model.gguf',
-    n_ctx: 2048,
-});
+### `CactusLMCompleteParams`
 
-const weatherTool = agent.addTool(
-    (location: string) => `Weather in ${location}: 72°F, sunny`,
-    'Get current weather for a location',
-    {
-        location: { type: 'string', description: 'City name', required: true }
-    }
-);
+```typescript
+interface CactusLMCompleteParams {
+  messages: Message[];
+  options?: Options;
+  tools?: Tool[];
+  onToken?: (token: string) => void;
+}
+```
+
+### `CactusLMCompleteResult`
+
+```typescript
+interface CactusLMCompleteResult {
+  success: boolean;
+  response: string;
+  functionCalls?: {
+    name: string;
+    arguments: { [key: string]: any };
+  }[];
+  timeToFirstTokenMs: number;
+  totalTimeMs: number;
+  tokensPerSecond: number;
+  prefillTokens: number;
+  decodeTokens: number;
+  totalTokens: number;
+}
+```
+
+### `CactusLMEmbedParams`
+
+```typescript
+interface CactusLMEmbedParams {
+  text: string;
+}
+```
+
+### `CactusLMEmbedResult`
+
+```typescript
+interface CactusLMEmbedResult {
+  embedding: number[];
+}
+```
+
+### `CactusLMGetModelsParams`
+
+```typescript
+interface CactusLMGetModelsParams {
+  forceRefresh?: boolean;
+}
+```
+
+### `CactusModel`
+
+```typescript
+interface CactusModel {
+  name: string;
+  slug: string;
+  quantization: number;
+  sizeMb: number;
+  downloadUrl: string;
+  supportsToolCalling: boolean;
+  supportsVision: boolean;
+  createdAt: Date;
+  isDownloaded: boolean;
+}
+```
+
+## Configuration
+
+### Telemetry
+
+Cactus offers powerful telemetry for all your projects. Create a token on the [Cactus dashboard](https://www.cactuscompute.com/dashboard).
+
+```typescript
+import { CactusConfig } from 'cactus-react-native';
 
-const messages = [{ role: 'user', content: 'What\'s the weather in NYC?' }];
-  const result = await agent.completionWithTools(messages, {
-  n_predict: 200,
-  temperature: 0.7,
-});
+// Enable Telemetry for your project
+CactusConfig.telemetryToken = 'your-token-here';
 
-await agent.release();
+// Disable telemetry
+CactusConfig.isTelemetryEnabled = false;
 ```

package/android/CMakeLists.txt

@@ -0,0 +1,40 @@
+project(cactus)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME cactus)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED 
+    src/main/cpp/cpp-adapter.cpp
+    ../cpp/HybridCactus.cpp
+    ../cpp/HybridCactusUtil.cpp
+)
+
+add_library(libcactus STATIC IMPORTED)
+set_target_properties(libcactus PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/src/main/jniLibs/${ANDROID_ABI}/libcactus.a"
+)
+
+add_library(libcactus_util SHARED IMPORTED)
+set_target_properties(libcactus_util PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/src/main/jniLibs/${ANDROID_ABI}/libcactus_util.so"
+)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/cactus+autolinking.cmake)
+
+# Set up local includes
+include_directories("src/main/cpp" "../cpp")
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android # <-- Android core
+        libcactus
+        libcactus_util
+)