# Table of Contents

- [Overview](#overview)
- [Flutter SDK](#flutter-sdk)
- [C++ SDK](#c-sdk)
- [Kotlin Multiplatform SDK](#kotlin-multiplatform-sdk)
- [React Native SDK](#react-native-sdk)

---

# Overview

Overview
========

Cross-platform framework for deploying language, vision, and speech models locally on smartphones.

![Cactus SDK Banner](https://cactuscompute.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fbanner.be0d5ad7.jpg&w=3840&q=75&dpl=dpl_BsCc9eAC9j8DKHhp6h7Zom38U7eU)

[Cactus SDK](https://cactuscompute.com/docs#cactus-sdk)

========================================================

Cactus is the fastest cross-platform framework for deploying AI locally on smartphones.

[Quick Start](https://cactuscompute.com/docs#quick-start)

----------------------------------------------------------

Choose your preferred platform:

[### React Native SDK\
\
Learn about our React Native implementation](https://cactuscompute.com/docs/react-native)
[### Flutter SDK\
\
Learn about our Flutter implementation](https://cactuscompute.com/docs/flutter)
[### Kotlin Multiplatform SDK\
\
Learn about our KMP implementation](https://cactuscompute.com/docs/kotlin)
[### C++ SDK\
\
Native C++ development guide](https://cactuscompute.com/docs/cpp)

[v1 Release Feature List](https://cactuscompute.com/docs#v1-release-feature-list)

----------------------------------------------------------------------------------

After months of development and feedback from our community, we're launching the new Cactus SDK with significant architectural improvements and performance optimizations.

The table below outlines feature support across SDK versions.

|     | v0  |     | v1  |     |     |
| --- | --- | --- | --- | --- | --- |
|     | React Native | Flutter | React Native | Flutter | Kotlin |
| --- | --- | --- | --- | --- | --- |
| LLM Inference |     |     |     |     |     |
| Tool calling |     |     |     |     |     |
| Embeddings |     |     |     |     |     |
| Voice transcription |     |     |     |     |     |
| Voice synthesis |     |     | Soon | Soon | Soon |
| Image embedding |     |     |     | Soon | Soon |
| RAG |     |     | Soon |     | Soon |
| Model format | GGUF | GGUF | Cactus | Cactus | Cactus |

\* Production benchmarks using Qwen3 0.6B Q8 running CPU-only inference on an iPhone 16 Pro Max

[Performance Benchmarks](https://cactuscompute.com/docs#performance-benchmarks)

--------------------------------------------------------------------------------

Real-world performance on popular mobile devices:

| Device | Gemma3 1B Q4 (toks/sec) | Qwen3 4B Q4 (toks/sec) |
| --- | --- | --- |
| iPhone 16 Pro Max | 54  | 18  |
| iPhone 16 Pro | 54  | 18  |
| iPhone 16 | 49  | 16  |
| iPhone 15 Pro Max | 45  | 15  |
| iPhone 15 Pro | 45  | 15  |
| iPhone 14 Pro Max | 44  | 14  |
| OnePlus 13 5G | 43  | 14  |
| Samsung Galaxy S24 Ultra | 42  | 14  |
| iPhone 15 | 42  | 14  |
| OnePlus Open | 38  | 13  |
| Samsung Galaxy S23 5G | 37  | 12  |
| Samsung Galaxy S24 | 36  | 12  |
| iPhone 13 Pro | 35  | 11  |
| OnePlus 12 | 35  | 11  |
| Galaxy S25 Ultra | 29  | 9   |
| OnePlus 11 | 26  | 8   |
| iPhone 13 mini | 25  | 8   |
| Redmi K70 Ultra | 24  | 8   |
| Xiaomi 13 | 24  | 8   |
| Samsung Galaxy S24+ | 22  | 7   |
| Samsung Galaxy Z Fold 4 | 22  | 7   |
| Xiaomi Poco F6 5G | 22  | 6   |

[Demo Apps](https://cactuscompute.com/docs#demo-apps)

------------------------------------------------------

Try our demo applications to see Cactus SDK in action:

[### iOS App Store\
\
Download for iPhone/iPad](https://apps.apple.com/gb/app/cactus-chat/id6744444212)
[### Google Play Store\
\
Download for Android](https://play.google.com/store/apps/details?id=com.rshemetsubuser.myapp)

[Next Steps](https://cactuscompute.com/docs#next-steps)

--------------------------------------------------------

[### Join our discord!\
\
Ask questions and engage with the community](https://discord.gg/nPGWGxXSwr)
[### View Recommended Models\
\
Browse our recommended models on HuggingFace](https://huggingface.co/Cactus-Compute)

[Community](https://cactuscompute.com/docs#community)

------------------------------------------------------

*   [Join our Discord](https://discord.gg/bNurx3AXTJ)
     - Get help and connect with other developers
*   [Visualize Repository](https://repomapr.com/cactus-compute/cactus)
     - Explore the codebase structure
*   [GitHub Repository](https://github.com/cactus-compute/cactus)
     - View source code and contribute

[Flutter SDK\
\
Complete guide to using Cactus SDK in Flutter applications](https://cactuscompute.com/docs/flutter)

### On this page

[Cactus SDK](https://cactuscompute.com/docs#cactus-sdk)
[Quick Start](https://cactuscompute.com/docs#quick-start)
[v1 Release Feature List](https://cactuscompute.com/docs#v1-release-feature-list)
[Performance Benchmarks](https://cactuscompute.com/docs#performance-benchmarks)
[Demo Apps](https://cactuscompute.com/docs#demo-apps)
[Next Steps](https://cactuscompute.com/docs#next-steps)
[Community](https://cactuscompute.com/docs#community)

---

# Flutter SDK

Flutter SDK
===========

Complete guide to using Cactus SDK in Flutter applications

[Cactus Flutter](https://cactuscompute.com/docs/flutter#cactus-flutter)

========================================================================

Official Flutter library for Cactus, a framework for deploying LLM and STT models locally in your app.

[Video walkthrough](https://cactuscompute.com/docs/flutter#video-walkthrough)

------------------------------------------------------------------------------

Build an example app in 5 minutes by following this video:

[Installation](https://cactuscompute.com/docs/flutter#installation)

--------------------------------------------------------------------

Execute the following command in your project terminal:

    flutter pub add cactus

**Platform Requirements:**

*   **iOS**: iOS 12.0+
*   **Android**: API level 24+

[Quickstart](https://cactuscompute.com/docs/flutter#quickstart)

----------------------------------------------------------------

Get started from scratch by cloning our [example app](https://github.com/cactus-compute/cactus-flutter/tree/main/example)
.

[Language Model (LLM)](https://cactuscompute.com/docs/flutter#language-model-llm)

----------------------------------------------------------------------------------

The `CactusLM` class provides text completion capabilities with high-performance local inference.

### [Basic Usage](https://cactuscompute.com/docs/flutter#basic-usage)

**Download Model**

Download a model by slug (e.g., "qwen3-0.6", "gemma3-270m"). If no model is specified, it defaults to "qwen3-0.6".

    await lm.downloadModel(
      model: "qwen3-0.6", // Optional: specify model slug
      downloadProcessCallback: (progress, status, isError) {
        if (isError) {
          print("Download error: $status");
        } else {
          print("$status ${progress != null ? '(${progress * 100}%)' : ''}");
        }
      },
    );

**Initialize Model**

Initialize the downloaded model for inference.

    await lm.initializeModel();

**Generate Completion**

Generate a completion with default parameters.

    final result = await lm.generateCompletion(
      messages: [\
        ChatMessage(content: "Hello, how are you?", role: "user"),\
      ],
    );
    
    if (result.success) {
      print("Response: ${result.response}");
      print("Tokens per second: ${result.tokensPerSecond}");
      print("Time to first token: ${result.timeToFirstTokenMs}ms");
    }

**Unload Model**

Clean up and free the model from memory.

    lm.unload();

See the full example in [`basic_completion.dart`](https://github.com/cactus-compute/cactus-flutter/blob/main/example/lib/pages/basic_completion.dart)
.

### [Streaming Completions](https://cactuscompute.com/docs/flutter#streaming-completions)

Get a streaming response and process the output as it's generated.

    final streamedResult = await lm.generateCompletionStream(
      messages: [ChatMessage(content: "Tell me a story", role: "user")],
    );
    
    await for (final chunk in streamedResult.stream) {
      print(chunk);
    }
    
    final finalResult = await streamedResult.result;
    if (finalResult.success) {
      print("Final response: ${finalResult.response}");
      print("Tokens per second: ${finalResult.tokensPerSecond}");
    }

See the full example in [`streaming_completion.dart`](https://github.com/cactus-compute/cactus-flutter/blob/main/example/lib/pages/streaming_completion.dart)
.

### [Function Calling](https://cactuscompute.com/docs/flutter#function-calling)

Define tools and let the model generate function calls.

    final tools = [\
      CactusTool(\
        name: "get_weather",\
        description: "Get current weather for a location",\
        parameters: ToolParametersSchema(\
          properties: {\
            'location': ToolParameter(type: 'string', description: 'City name', required: true),\
          },\
        ),\
      ),\
    ];
    
    final result = await lm.generateCompletion(
      messages: [ChatMessage(content: "What's the weather in New York?", role: "user")],
      params: CactusCompletionParams(
        tools: tools
      )
    );
    
    if (result.success) {
      print("Response: ${result.response}");
      print("Tools: ${result.toolCalls}");
    }

See the full example in [`function_calling.dart`](https://github.com/cactus-compute/cactus-flutter/blob/main/example/lib/pages/function_calling.dart)
.

### [Tool Filtering](https://cactuscompute.com/docs/flutter#tool-filtering)

When working with many tools, you can use tool filtering to automatically select the most relevant tools for each query.

    // Configure tool filtering via constructor (optional)
    final lm = CactusLM(
      enableToolFiltering: true,  // default: true
      toolFilterConfig: ToolFilterConfig.simple(maxTools: 3),  // default config if not specified
    );
    await lm.downloadModel(model: "qwen3-0.6");
    await lm.initializeModel();
    
    // Define multiple tools
    final tools = [\
      CactusTool(\
        name: "get_weather",\
        description: "Get current weather for a location",\
        parameters: ToolParametersSchema(\
          properties: {\
            'location': ToolParameter(type: 'string', description: 'City name', required: true),\
          },\
        ),\
      ),\
      CactusTool(\
        name: "get_stock_price",\
        description: "Get current stock price for a company",\
        parameters: ToolParametersSchema(\
          properties: {\
            'symbol': ToolParameter(type: 'string', description: 'Stock symbol', required: true),\
          },\
        ),\
      ),\
      CactusTool(\
        name: "send_email",\
        description: "Send an email to someone",\
        parameters: ToolParametersSchema(\
          properties: {\
            'to': ToolParameter(type: 'string', description: 'Email address', required: true),\
            'subject': ToolParameter(type: 'string', description: 'Email subject', required: true),\
            'body': ToolParameter(type: 'string', description: 'Email body', required: true),\
          },\
        ),\
      ),\
    ];
    
    // Tool filtering happens automatically!
    final result = await lm.generateCompletion(
      messages: [ChatMessage(content: "What's the weather in Paris?", role: "user")],
      params: CactusCompletionParams(
        tools: tools
      )
    );
    
    if (result.success) {
      print("Response: ${result.response}");
      print("Tool calls: ${result.toolCalls}");
    }
    
    lm.unload();

**Note:** When tool filtering is active, you'll see debug output like:

    Tool filtering: 3 -> 1 tools
    Filtered tools: get_weather

### [Hybrid Completion (Cloud Fallback)](https://cactuscompute.com/docs/flutter#hybrid-completion-cloud-fallback)

The `CactusLM` supports a `hybrid` completion mode that falls back to a cloud-based LLM provider (OpenRouter) if local inference fails or is not available. This ensures reliability and provides a seamless experience.

To use hybrid mode:

1.  Set `completionMode` to `CompletionMode.hybrid` in `CactusCompletionParams`.
2.  Provide a `cactusToken` in `CactusCompletionParams`.

To get a `cactusToken`, join our [Discord community](https://discord.gg/nPGWGxXSwr)
 and contact us.

    final result = await lm.generateCompletion(
      messages: [ChatMessage(content: "What's the weather in New York?", role: "user")],
      params: CactusCompletionParams(
        completionMode: CompletionMode.hybrid,
        cactusToken: "YOUR_CACTUS_TOKEN"
      ),
    );
    
    if (result.success) {
      print("Response: ${result.response}");
    }

See the full example in [`hybrid_completion.dart`](https://github.com/cactus-compute/cactus-flutter/blob/main/example/lib/pages/hybrid_completion.dart)
.

### [Fetching Available Models](https://cactuscompute.com/docs/flutter#fetching-available-models)

    // Get list of available models with caching
    final models = await lm.getModels();
    
    for (final model in models) {
      print("Model: ${model.name}");
      print("Slug: ${model.slug}");
      print("Size: ${model.sizeMb} MB");
      print("Downloaded: ${model.isDownloaded}");
      print("Supports Tool Calling: ${model.supportsToolCalling}");
      print("Supports Vision: ${model.supportsVision}");
      print("---");
    }

See the full example in [`fetch_models.dart`](https://github.com/cactus-compute/cactus-flutter/blob/main/example/lib/pages/fetch_models.dart)
.

[Vision (Multimodal)](https://cactuscompute.com/docs/flutter#vision-multimodal)

--------------------------------------------------------------------------------

The `CactusLM` class supports vision-capable models that can analyze images. You can pass images alongside text messages to get AI-powered image descriptions and analysis.

### [Vision Analysis](https://cactuscompute.com/docs/flutter#vision-analysis)

    Future<void> streamingVisionExample() async {
      final lm = CactusLM();
      await lm.initializeModel(params: CactusInitParams(model: 'lfm2-vl-450m'));
    
      // Stream the image analysis response
      final streamedResult = await lm.generateCompletionStream(
        messages: [\
          ChatMessage(\
            content: 'What objects can you see in this image?',\
            role: "user",\
            images: ['/path/to/image.jpg']\
          )\
        ],
        params: CactusCompletionParams(maxTokens: 200)
      );
    
      // Process streaming output
      await for (final chunk in streamedResult.stream) {
        print(chunk);
      }
    
      lm.unload();
    }

See the full example in [`vision.dart`](https://github.com/cactus-compute/cactus-flutter/blob/main/example/lib/pages/vision.dart)
.

### [Default Parameters](https://cactuscompute.com/docs/flutter#default-parameters)

The `CactusLM` class provides sensible defaults for completion parameters:

*   `maxTokens: 200` - Maximum tokens to generate
*   `stopSequences: ["<|im_end|>", "<end_of_turn>"]` - Stop sequences for completion
*   `completionMode: CompletionMode.local` - Default to local-only inference.

### [LLM API Reference](https://cactuscompute.com/docs/flutter#llm-api-reference)

#### [CactusLM Class](https://cactuscompute.com/docs/flutter#cactuslm-class)

*   `CactusLM({bool enableToolFiltering = true, ToolFilterConfig? toolFilterConfig})` - Constructor. Set `enableToolFiltering` to false to disable automatic tool filtering. Provide `toolFilterConfig` to customize filtering behavior (defaults to `ToolFilterConfig.simple()` if not specified).
*   `Future<void> downloadModel({String model = "qwen3-0.6", CactusProgressCallback? downloadProcessCallback})` - Download a model by slug (e.g., "qwen3-0.6", "gemma3-270m", etc.). Use `getModels()` to see available model slugs. Defaults to "qwen3-0.6" if not specified.
*   `Future<void> initializeModel({CactusInitParams? params})` - Initialize model for inference
*   `Future<CactusCompletionResult> generateCompletion({required List<ChatMessage> messages, CactusCompletionParams? params})` - Generate text completion (uses default params if none provided). Automatically filters tools if `enableToolFiltering` is true (default).
*   `Future<CactusStreamedCompletionResult> generateCompletionStream({required List<ChatMessage> messages, CactusCompletionParams? params})` - Generate streaming text completion (uses default params if none provided). Automatically filters tools if `enableToolFiltering` is true (default).
*   `Future<List<CactusModel>> getModels()` - Fetch available models with caching
*   `Future<CactusEmbeddingResult> generateEmbedding({required String text, String? modelName})` - Generate text embeddings
*   `void unload()` - Free model from memory
*   `bool isLoaded()` - Check if model is loaded

#### [Data Classes](https://cactuscompute.com/docs/flutter#data-classes)

*   `CactusInitParams({String model = "qwen3-0.6", int? contextSize = 2048})` - Model initialization parameters
*   `CactusCompletionParams({String? model, double? temperature, int? topK, double? topP, int maxTokens = 200, List<String> stopSequences = ["<|im_end|>", "<end_of_turn>"], List<CactusTool>? tools, CompletionMode completionMode = CompletionMode.local, String? cactusToken})` - Completion parameters
*   `ChatMessage({required String content, required String role, int? timestamp, List<String>? images})` - Chat message format with optional image paths
*   `CactusCompletionResult({required bool success, required String response, required double timeToFirstTokenMs, required double totalTimeMs, required double tokensPerSecond, required int prefillTokens, required int decodeTokens, required int totalTokens, List<ToolCall> toolCalls = []})` - Contains response, timing metrics, tool calls, and success status
*   `CactusStreamedCompletionResult({required Stream<String> stream, required Future<CactusCompletionResult> result})` - Contains the stream and the final result of a streamed completion.
*   `CactusModel({required DateTime createdAt, required String slug, required String downloadUrl, required int sizeMb, required bool supportsToolCalling, required bool supportsVision, required String name, bool isDownloaded = false, int quantization = 8})` - Model information
*   `CactusEmbeddingResult({required bool success, required List<double> embeddings, required int dimension, String? errorMessage})` - Embedding generation result
*   `CactusTool({required String name, required String description, required ToolParametersSchema parameters})` - Function calling tool definition
*   `ToolParametersSchema({String type = 'object', required Map<String, ToolParameter> properties})` - Tool parameters schema with automatic required field extraction
*   `ToolParameter({required String type, required String description, bool required = false})` - Tool parameter specification
*   `ToolCall({required String name, required Map<String, String> arguments})` - Tool call result from model
*   `ToolFilterConfig({ToolFilterStrategy strategy = ToolFilterStrategy.simple, int? maxTools, double similarityThreshold = 0.3})` - Configuration for tool filtering behavior
    *   Factory: `ToolFilterConfig.simple({int maxTools = 3})` - Creates a simple keyword-based filter config
*   `ToolFilterStrategy` - Enum for tool filtering strategy (`simple` for keyword matching, `semantic` for embedding-based matching)
*   `ToolFilterService({ToolFilterConfig? config, required CactusLM lm})` - Service for filtering tools based on query relevance (used internally)
*   `CactusProgressCallback = void Function(double? progress, String statusMessage, bool isError)` - Progress callback for downloads
*   `CompletionMode` - Enum for completion mode (`local` or `hybrid`).

[Embeddings](https://cactuscompute.com/docs/flutter#embeddings)

----------------------------------------------------------------

The `CactusLM` class also provides text embedding generation capabilities for semantic similarity, search, and other NLP tasks.

### [Basic Usage](https://cactuscompute.com/docs/flutter#basic-usage-1)

**Download and Initialize** Download and initialize a model, same as for completions.

    await lm.downloadModel();
    await lm.initializeModel();

**Generate Embeddings** Generate embeddings for a piece of text.

    final result = await lm.generateEmbedding(
      text: "This is a sample text for embedding generation",
    );
    
    if (result.success) {
      print("Embedding dimension: ${result.dimension}");
      print("Embedding vector length: ${result.embeddings.length}");
      print("First few values: ${result.embeddings.take(5)}");
    } else {
      print("Embedding generation failed: ${result?.errorMessage}");
    }

See the full example in [`embedding.dart`](https://github.com/cactus-compute/cactus-flutter/blob/main/example/lib/pages/embedding.dart)
.

### [Embedding API Reference](https://cactuscompute.com/docs/flutter#embedding-api-reference)

#### [CactusLM Class (Embedding Methods)](https://cactuscompute.com/docs/flutter#cactuslm-class-embedding-methods)

*   `Future<CactusEmbeddingResult?> generateEmbedding({required String text})` - Generate text embeddings

#### [Embedding Data Classes](https://cactuscompute.com/docs/flutter#embedding-data-classes)

*   `CactusEmbeddingResult({required bool success, required List<double> embeddings, required int dimension, String? errorMessage})` - Contains the generated embedding vector and metadata

[Speech-to-Text (STT)](https://cactuscompute.com/docs/flutter#speech-to-text-stt)

----------------------------------------------------------------------------------

The `CactusSTT` class provides high-quality local speech recognition capabilities with support for multiple transcription providers. It supports multiple languages and runs entirely on-device for privacy and offline functionality.

**Available Providers:**

*   **Whisper**: OpenAI's robust speech recognition model (default)

### [Basic Usage](https://cactuscompute.com/docs/flutter#basic-usage-2)

      final stt = CactusSTT();
    
      try {
      // Download and initialize model (defaults to Whisper)
        await stt.downloadModel(
          model: "whisper-tiny",
          downloadProcessCallback: (progress, status, isError) {
            if (isError) {
              print("Download error: $status");
            } else {
              print("$status ${progress != null ? '(${progress * 100}%)' : ''}");
            }
          },
        );
        await stt.initializeModel(params: CactusInitParams(model: "whisper-tiny"));
    
        // Transcribe audio (from file)
        final result = await stt.transcribe();
    
      if (result != null && result.success) {
        print("Transcribed: ${result.text}");
      }
    } finally {
      stt.dispose();
    }

### [Default Parameters](https://cactuscompute.com/docs/flutter#default-parameters-1)

The `CactusSTT` class uses sensible defaults for speech recognition:

*   `provider: TranscriptionProvider.whisper` - Default transcription provider
*   `model: "whisper-tiny"` - Default Whisper model
*   `sampleRate: 16000` - Standard sample rate for speech recognition
*   `maxDuration: 30000` - Maximum 30 seconds recording time

### [STT API Reference](https://cactuscompute.com/docs/flutter#stt-api-reference)

#### [CactusSTT Class](https://cactuscompute.com/docs/flutter#cactusstt-class)

*   `CactusSTT()` - Constructor
*   `Future<void> downloadModel({required String model, CactusProgressCallback? downloadProcessCallback})` - Download a voice model (e.g., "whisper-tiny", "whisper-base")
*   `Future<void> initializeModel({CactusInitParams? params})` - Initialize speech recognition model (uses last initialized model if params not provided)
*   `Future<CactusTranscriptionResult> transcribe({required String audioFilePath, String prompt = whisperPrompt, CactusTranscriptionParams? params})` - Transcribe audio from file path
*   `Future<CactusStreamedTranscriptionResult> transcribeStream({required String audioFilePath, String prompt = whisperPrompt, CactusTranscriptionParams? params})` - Stream transcription token by token
*   `void unload()` - Free model from memory
*   `bool isLoaded()` - Check if model is loaded
*   `Future<List<VoiceModel>> getVoiceModels()` - Fetch available voice models with caching

#### [STT Data Classes](https://cactuscompute.com/docs/flutter#stt-data-classes)

*   `CactusInitParams({String model = "qwen3-0.6", int? contextSize = 2048})` - Model initialization parameters (reused from LLM API)
*   `CactusTranscriptionParams({int maxTokens = 2048, List<String> stopSequences = ["<|startoftranscript|>"]})` - Transcription parameters
*   `CactusTranscriptionResult({required bool success, required String text, double timeToFirstTokenMs = 0.0, double totalTimeMs = 0.0, double tokensPerSecond = 0.0, String? errorMessage})` - Transcription result with timing metrics
*   `CactusStreamedTranscriptionResult({required Stream<String> stream, required Future<CactusTranscriptionResult> result})` - Contains the token stream and the final transcription result
*   `VoiceModel({required DateTime createdAt, required String slug, required String downloadUrl, required int sizeMb, required String fileName, bool isDownloaded = false})` - Voice model information
*   `CactusProgressCallback = void Function(double? progress, String statusMessage, bool isError)` - Progress callback for model downloads

[Retrieval-Augmented Generation (RAG)](https://cactuscompute.com/docs/flutter#retrieval-augmented-generation-rag)

------------------------------------------------------------------------------------------------------------------

The `CactusRAG` class provides a local vector database for storing, managing, and searching documents with automatic text chunking. It uses [ObjectBox](https://objectbox.io/)
 for efficient on-device storage and retrieval, making it ideal for building RAG applications that run entirely locally.

**Key Features:**

*   **Automatic Text Chunking**: Documents are automatically split into configurable chunks with overlap for better context preservation
*   **Embedding Generation**: Integrates with `CactusLM` to automatically generate embeddings for each chunk
*   **Vector Search**: Performs efficient nearest neighbor search using HNSW (Hierarchical Navigable Small World) index with squared Euclidean distance
*   **Document Management**: Supports create, read, update, and delete operations with automatic chunk handling
*   **Local-First**: All data and embeddings are stored on-device using ObjectBox for privacy and offline functionality

### [Basic Usage](https://cactuscompute.com/docs/flutter#basic-usage-3)

**Note on Distance Scores**: The search method returns squared Euclidean distance values where **lower distance = more similar** vectors. Results are automatically sorted with the most similar chunks first. You don't need to convert to similarity scores - just use the distance values directly for filtering or ranking.

    final lm = CactusLM();
    final rag = CactusRAG();
    
    try {
      // Initialize
      await lm.downloadModel();
      await lm.initializeModel();
      await rag.initialize();
    
      // Set up embedding generator
      rag.setEmbeddingGenerator((text) async {
        final result = await lm.generateEmbedding(text: text);
        return result.embeddings;
      });
    
      // Configure chunking parameters (optional - defaults: chunkSize=512, chunkOverlap=64)
      rag.setChunking(chunkSize: 1024, chunkOverlap: 128);
    
      // Store a document (automatically chunks and embeds)
      final document = await rag.storeDocument(
        fileName: "document.txt",
        filePath: "/path/to/document.txt",
        content: "Your document content here...",
        fileSize: 1024,
      );
    
      // Search for similar content
      final searchResults = await rag.search(
        text: "What is the famous landmark in Paris?",
        limit: 5, // Get top 5 most similar chunks
      );
    
      for (final result in searchResults) {
        print("- Chunk from \${result.chunk.document.target?.fileName} (Distance: \${result.distance.toStringAsFixed(2)})");
        print("  Content: \${result.chunk.content.substring(0, 50)}...");
      }
    } finally {
      lm.unload();
      await rag.close();
    }

### [RAG API Reference](https://cactuscompute.com/docs/flutter#rag-api-reference)

#### [CactusRAG Class](https://cactuscompute.com/docs/flutter#cactusrag-class)

*   `Future<void> initialize()` - Initialize the local ObjectBox database
*   `Future<void> close()` - Close the database connection
*   `void setEmbeddingGenerator(EmbeddingGenerator generator)` - Set the function used to generate embeddings for text chunks
*   `void setChunking({required int chunkSize, required int chunkOverlap})` - Configure text chunking parameters (defaults: chunkSize=512, chunkOverlap=64)
*   `int get chunkSize` - Get current chunk size setting
*   `int get chunkOverlap` - Get current chunk overlap setting
*   `List<String> chunkContent(String content, {int? chunkSize, int? chunkOverlap})` - Manually chunk text content (visible for testing)
*   `Future<Document> storeDocument({required String fileName, required String filePath, required String content, int? fileSize, String? fileHash})` - Store a document with automatic chunking and embedding generation
*   `Future<Document?> getDocumentByFileName(String fileName)` - Retrieve a document by its file name
*   `Future<List<Document>> getAllDocuments()` - Get all stored documents
*   `Future<void> updateDocument(Document document)` - Update an existing document and its chunks
*   `Future<void> deleteDocument(int id)` - Delete a document and all its chunks by ID
*   `Future<List<ChunkSearchResult>> search({String? text, int limit = 10})` - Search for the nearest document chunks by generating embeddings for the query text and performing vector similarity search. Results are sorted by distance (lower = more similar)
*   `Future<DatabaseStats> getStats()` - Get statistics about the database

#### [RAG Data Classes](https://cactuscompute.com/docs/flutter#rag-data-classes)

*   `Document({int id = 0, required String fileName, required String filePath, DateTime? createdAt, DateTime? updatedAt, int? fileSize, String? fileHash})` - Represents a stored document with its metadata and associated chunks. Has a `content` getter that joins all chunk contents.
*   `DocumentChunk({int id = 0, required String content, required List<double> embeddings})` - Represents a text chunk with its content and embeddings (1024-dimensional vectors by default)
*   `ChunkSearchResult({required DocumentChunk chunk, required double distance})` - Contains a document chunk and its distance score from the query vector (lower distance = more similar). Distance is squared Euclidean distance from ObjectBox HNSW index
*   `DatabaseStats({required int totalDocuments, required int documentsWithEmbeddings, required int totalContentLength})` - Contains statistics about the document store including total documents, chunks, and content length
*   `EmbeddingGenerator = Future<List<double>> Function(String text)` - Function type for generating embeddings from text

See the full example in [`rag.dart`](https://github.com/cactus-compute/cactus-flutter/blob/main/example/lib/pages/rag.dart)
.

[Platform-Specific Setup](https://cactuscompute.com/docs/flutter#platform-specific-setup)

------------------------------------------------------------------------------------------

### [Android](https://cactuscompute.com/docs/flutter#android)

Add the following permissions to your `android/app/src/main/AndroidManifest.xml`:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- Required for speech-to-text functionality -->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />

### [iOS](https://cactuscompute.com/docs/flutter#ios)

Add microphone usage description to your `ios/Runner/Info.plist` for speech-to-text functionality:

    <key>NSMicrophoneUsageDescription</key>
    <string>This app needs access to the microphone for speech-to-text transcription.</string>

### [macOS](https://cactuscompute.com/docs/flutter#macos)

Add the following to your `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`:

    <!-- Network access for model downloads -->
    <key>com.apple.security.network.client</key>
    <true/>
    <!-- Microphone access for speech-to-text -->
    <key>com.apple.security.device.microphone</key>
    <true/>

[Performance Tips](https://cactuscompute.com/docs/flutter#performance-tips)

----------------------------------------------------------------------------

1.  **Model Selection**: Choose smaller models for faster inference on mobile devices
2.  **Context Size**: Reduce context size for lower memory usage (e.g., 1024 instead of 2048)
3.  **Memory Management**: Always call `unload()` when done with models
4.  **Batch Processing**: Reuse initialized models for multiple completions
5.  **Background Processing**: Use `Isolate` for heavy operations to keep UI responsive
6.  **Model Caching**: Use `getModels()` for efficient model discovery - results are cached locally to reduce network requests

[Telemetry Setup (Optional)](https://cactuscompute.com/docs/flutter#telemetry-setup-optional)

----------------------------------------------------------------------------------------------

Cactus comes with powerful built-in telemetry that lets you monitor your projects. Create a token on the [Cactus dashboard](https://cactuscompute.com/dashboard/telemetry-tokens)
 and get started with a one-line setup in your app:

    import 'package:cactus/cactus.dart';
    
    CactusTelemetry.setTelemetryToken("your-token-here");

[Example App](https://cactuscompute.com/docs/flutter#example-app)

------------------------------------------------------------------

Check out [our example app](https://github.com/cactus-compute/cactus-flutter/tree/main/example)
 for a complete Flutter implementation showing:

*   Model discovery and fetching available models
*   Model downloading with real-time progress indicators
*   Text completion with both regular and streaming modes
*   Vision/multimodal image analysis
*   Speech-to-text transcription with Whisper
*   Voice model management and provider switching
*   Embedding generation
*   RAG document storage and search
*   Error handling and status management
*   Material Design UI integration

To run the example:

    cd example
    flutter pub get
    flutter run

[Next Steps](https://cactuscompute.com/docs/flutter#next-steps)

----------------------------------------------------------------

[### React Native SDK\
\
Learn about our React Native implementation](https://cactuscompute.com/docs/react-native)
[### Kotlin Multiplatform SDK\
\
Learn about our KMP implementation](https://cactuscompute.com/docs/kotlin)
[### C++ SDK\
\
Native C++ development guide](https://cactuscompute.com/docs/cpp)
[### Join our discord!\
\
Ask questions and engage with the community](https://discord.gg/nPGWGxXSwr)

[Overview\
\
Cross-platform framework for deploying language, vision, and speech models locally on smartphones.](https://cactuscompute.com/docs)
[React Native SDK\
\
Complete guide to using Cactus SDK in React Native applications](https://cactuscompute.com/docs/react-native)

### On this page

[Cactus Flutter](https://cactuscompute.com/docs/flutter#cactus-flutter)
[Video walkthrough](https://cactuscompute.com/docs/flutter#video-walkthrough)
[Installation](https://cactuscompute.com/docs/flutter#installation)
[Quickstart](https://cactuscompute.com/docs/flutter#quickstart)
[Language Model (LLM)](https://cactuscompute.com/docs/flutter#language-model-llm)
[Basic Usage](https://cactuscompute.com/docs/flutter#basic-usage)
[Streaming Completions](https://cactuscompute.com/docs/flutter#streaming-completions)
[Function Calling](https://cactuscompute.com/docs/flutter#function-calling)
[Tool Filtering](https://cactuscompute.com/docs/flutter#tool-filtering)
[Hybrid Completion (Cloud Fallback)](https://cactuscompute.com/docs/flutter#hybrid-completion-cloud-fallback)
[Fetching Available Models](https://cactuscompute.com/docs/flutter#fetching-available-models)
[Vision (Multimodal)](https://cactuscompute.com/docs/flutter#vision-multimodal)
[Vision Analysis](https://cactuscompute.com/docs/flutter#vision-analysis)
[Default Parameters](https://cactuscompute.com/docs/flutter#default-parameters)
[LLM API Reference](https://cactuscompute.com/docs/flutter#llm-api-reference)
[CactusLM Class](https://cactuscompute.com/docs/flutter#cactuslm-class)
[Data Classes](https://cactuscompute.com/docs/flutter#data-classes)
[Embeddings](https://cactuscompute.com/docs/flutter#embeddings)
[Basic Usage](https://cactuscompute.com/docs/flutter#basic-usage-1)
[Embedding API Reference](https://cactuscompute.com/docs/flutter#embedding-api-reference)
[CactusLM Class (Embedding Methods)](https://cactuscompute.com/docs/flutter#cactuslm-class-embedding-methods)
[Embedding Data Classes](https://cactuscompute.com/docs/flutter#embedding-data-classes)
[Speech-to-Text (STT)](https://cactuscompute.com/docs/flutter#speech-to-text-stt)
[Basic Usage](https://cactuscompute.com/docs/flutter#basic-usage-2)
[Default Parameters](https://cactuscompute.com/docs/flutter#default-parameters-1)
[STT API Reference](https://cactuscompute.com/docs/flutter#stt-api-reference)
[CactusSTT Class](https://cactuscompute.com/docs/flutter#cactusstt-class)
[STT Data Classes](https://cactuscompute.com/docs/flutter#stt-data-classes)
[Retrieval-Augmented Generation (RAG)](https://cactuscompute.com/docs/flutter#retrieval-augmented-generation-rag)
[Basic Usage](https://cactuscompute.com/docs/flutter#basic-usage-3)
[RAG API Reference](https://cactuscompute.com/docs/flutter#rag-api-reference)
[CactusRAG Class](https://cactuscompute.com/docs/flutter#cactusrag-class)
[RAG Data Classes](https://cactuscompute.com/docs/flutter#rag-data-classes)
[Platform-Specific Setup](https://cactuscompute.com/docs/flutter#platform-specific-setup)
[Android](https://cactuscompute.com/docs/flutter#android)
[iOS](https://cactuscompute.com/docs/flutter#ios)
[macOS](https://cactuscompute.com/docs/flutter#macos)
[Performance Tips](https://cactuscompute.com/docs/flutter#performance-tips)
[Telemetry Setup (Optional)](https://cactuscompute.com/docs/flutter#telemetry-setup-optional)
[Example App](https://cactuscompute.com/docs/flutter#example-app)
[Next Steps](https://cactuscompute.com/docs/flutter#next-steps)

---

# C++ SDK

C++ SDK
=======

Complete guide to using Cactus SDK with C++ applications for native development

[Cactus C++](https://cactuscompute.com/docs/cpp#cactus-c)

==========================================================

Energy-efficient AI inference framework and kernels for smartphones & AI-native hardware.

Budget and mid-range phones control over 70% of the market, but frameworks today optimise for high-end phones with advanced chips.

Cactus is designed bottom-up with no dependencies for all mobile devices.

[Architecture](https://cactuscompute.com/docs/cpp#architecture)

----------------------------------------------------------------

Cactus exposes 4 levels of abstraction:

    ┌─────────────────┐
    │   Cactus FFI    │ ←── OpenAI compatible C API for integration  
    └─────────────────┘
             │
    ┌─────────────────┐
    │  Cactus Engine  │ ←── High-level transformer engine
    └─────────────────┘
             │
    ┌─────────────────┐  
    │  Cactus Graph   │ ←── Unified zero-copy computation graph 
    └─────────────────┘
             │
    ┌─────────────────┐
    │ Cactus Kernels  │ ←── Low-level ARM-specific SIMD operations
    └─────────────────┘

[Cactus Graph](https://cactuscompute.com/docs/cpp#cactus-graph)

----------------------------------------------------------------

Cactus Graph is a general numerical computing framework that runs on Cactus Kernels. Great for implementing custom models and scientific computing, like JAX for phones.

    #include cactus.h
    
    CactusGraph graph;
    
    auto a = graph.input({2, 3}, Precision::FP16);
    auto b = graph.input({3, 4}, Precision::INT8);
    
    auto x1 = graph.matmul(a, b, false);
    auto x2 = graph.transpose(x1);
    auto result = graph.matmul(b, x2, true);
    
    float a_data[6] = {1.1f, 2.3f, 3.4f, 4.2f, 5.7f, 6.8f};
    float b_data[12] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};
    
    graph.set_input(a, a_data, Precision::FP16);
    graph.set_input(b, b_data, Precision::INT8);
    graph.execute();
    
    void* output_data = graph.get_output(result);
    graph.hard_reset(); 

[Cactus Engine](https://cactuscompute.com/docs/cpp#cactus-engine)

------------------------------------------------------------------

Cactus Engine is a transformer inference engine built on top of Cactus Graphs. It is abstracted via the minimalist Cactus Foreign Function Interface.

    #include cactus.h
    
    const char* model_path = "path/to/weight/folder";
    cactus_model_t model = cactus_init(model_path, 2048);
    
    const char* messages = R"([\
        {"role": "system", "content": "You are a helpful assistant."},\
        {"role": "user", "content": "/nothink My name is Henry Ndubuaku"}\
    ])";
    
    const char* options = R"({
        "temperature": 0.1,
        "top_p": 0.95,
        "top_k": 20,
        "max_tokens": 50,
        "stop_sequences": ["<|im_end|>"]
    })";
    
    char response[1024];
    int result = cactus_complete(model, messages, response, sizeof(response), options, nullptr, nullptr, nullptr);

With tool calling support:

    const char* tools = R"([\
        {\
            "function": {\
                "name": "get_weather",\
                "description": "Get weather for a location",\
                "parameters": {\
                    "properties": {\
                        "location": {\
                            "type": "string",\
                            "description": "City name",\
                            "required": true\
                        }\
                    },\
                    "required": ["location"]\
                }\
            }\
        }\
    ])";
    
    int result = cactus_complete(model, messages, response, sizeof(response), options, tools, nullptr, nullptr);

This makes it easy to write Cactus bindings for any language. Header files are self-documenting, but documentation contributions are welcome.

[Using Cactus in your apps](https://cactuscompute.com/docs/cpp#using-cactus-in-your-apps)

==========================================================================================

Cactus SDKs process over 500,000 weekly inference tasks in production every week. Give them a try!

[### Flutter SDK\
\
Cross-platform mobile development in Flutter](https://cactuscompute.com/docs/flutter)
[### React Native SDK\
\
Cross-platform mobile development in React Native](https://cactuscompute.com/docs/react-native)

  

[Demo](https://cactuscompute.com/docs/cpp#demo)

================================================

[### Try iOS Demo\
\
Ask questions and engage the community](https://apps.apple.com/gb/app/cactus-chat/id6744444212)
[### Try Android Demo\
\
Go directly to the codebase](https://play.google.com/store/apps/details?id=com.rshemetsubuser.myapp&pcampaignid=web_share)

  

[Run this code locally](https://cactuscompute.com/docs/cpp#run-this-code-locally)

==================================================================================

You can run the c++ code directly on any Mac with an Apple chip thanks to the shared design.

We see optimal performance gains on mobile devices, however for testing during development, a Vanilla M3 CPU-only can run Qwen3-600m-INT8 at 60-70 toks/sec:

### Pull weights

Generate weights from a HuggingFace model:

    python3 tools/convert_hf.py Qwen/Qwen3-0.6B weights/qwen3-600m-i8/ --precision INT8

### Execute

Build and test:

    ./tests/run.sh # remember to chmod +x any script first time

[Next steps](https://cactuscompute.com/docs/cpp#next-steps)

============================================================

[### Join our discord!\
\
Ask questions and engage the community](https://discord.gg/nPGWGxXSwr)
[### Check out the repo\
\
Go directly to the codebase](https://github.com/cactus-compute)

[Kotlin Multiplatform SDK\
\
Complete guide to using Cactus SDK in Kotlin applications](https://cactuscompute.com/docs/kotlin)

### On this page

[Cactus C++](https://cactuscompute.com/docs/cpp#cactus-c)
[Architecture](https://cactuscompute.com/docs/cpp#architecture)
[Cactus Graph](https://cactuscompute.com/docs/cpp#cactus-graph)
[Cactus Engine](https://cactuscompute.com/docs/cpp#cactus-engine)
[Using Cactus in your apps](https://cactuscompute.com/docs/cpp#using-cactus-in-your-apps)
[Demo](https://cactuscompute.com/docs/cpp#demo)
[Run this code locally](https://cactuscompute.com/docs/cpp#run-this-code-locally)
[Next steps](https://cactuscompute.com/docs/cpp#next-steps)

---

# Kotlin Multiplatform SDK

Kotlin Multiplatform SDK
========================

Complete guide to using Cactus SDK in Kotlin applications

[Cactus Kotlin](https://cactuscompute.com/docs/kotlin#cactus-kotlin)

=====================================================================

Official Kotlin Multiplatform library for Cactus, a framework for deploying LLM and STT models locally in your app.

[Installation](https://cactuscompute.com/docs/kotlin#installation)

-------------------------------------------------------------------

**Dependency List**

Add to `settings.gradle.kts`

    dependencyResolutionManagement {
        repositories {
            mavenCentral()
        }
    }

**Gradle Build**

Add to your KMP project's `build.gradle.kts`:

    kotlin {
        sourceSets {
            commonMain {
                dependencies {
                    implementation("com.cactuscompute:cactus:1.2.0-beta")
                }
            }
        }
    }

**Grant Permissions**

Add the permissions to your manifest (Android):

    <uses-permission android:name="android.permission.INTERNET" /> // for model downloads
    <uses-permission android:name="android.permission.RECORD_AUDIO" /> // for transcription

[Context Initialization (Required)](https://cactuscompute.com/docs/kotlin#context-initialization-required)

-----------------------------------------------------------------------------------------------------------

Before using any Cactus SDK functionality, you must initialize the context in your Activity's `onCreate()` method:

    import com.cactus.CactusContextInitializer
    
    class MainActivity : ComponentActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
    
            // Initialize Cactus context (required)
            CactusContextInitializer.initialize(this)
    
            // ... rest of your code
        }
    }

[Language Model (LLM)](https://cactuscompute.com/docs/kotlin#language-model-llm)

---------------------------------------------------------------------------------

The `CactusLM` class provides text completion capabilities with support for function calling (WIP).

### [Basic Usage](https://cactuscompute.com/docs/kotlin#basic-usage)

    import com.cactus.CactusLM
    import com.cactus.CactusInitParams
    import com.cactus.CactusCompletionParams
    import com.cactus.ChatMessage
    import kotlinx.coroutines.runBlocking
    
    runBlocking {
        val lm = CactusLM()
    
        try {
            // Download a model by slug (e.g., "qwen3-0.6", "gemma3-270m")
            // If no model is specified, it defaults to "qwen3-0.6"
            // Throws exception on failure
            lm.downloadModel("qwen3-0.6")
            
            // Initialize the model
            // Throws exception on failure
            lm.initializeModel(
                CactusInitParams(
                    model = "qwen3-0.6",
                    contextSize = 2048
                )
            )
    
            // Generate completion with default parameters
            val result = lm.generateCompletion(
                messages = listOf(
                    ChatMessage(content = "Hello, how are you?", role = "user")
                )
            )
    
            result?.let { response ->
                if (response.success) {
                    println("Response: ${response.response}")
                    println("Tokens per second: ${response.tokensPerSecond}")
                    println("Time to first token: ${response.timeToFirstTokenMs}ms")
                }
            }
        } finally {
            // Clean up
            lm.unload()
        }
    }

### [Inference Modes](https://cactuscompute.com/docs/kotlin#inference-modes)

`CactusLM` supports hybrid inference modes that allow fallback between local and cloud-based processing:

    val result = lm.generateCompletion(
        messages = listOf(ChatMessage(content = "Hello!", role = "user")),
        params = CactusCompletionParams(
            mode = InferenceMode.LOCAL_FIRST, // Try local first, fallback to cloud
            cactusToken = "your_cactus_token"
        )
    )

**Available modes:**

*   `InferenceMode.LOCAL` - Local inference only (default)
*   `InferenceMode.REMOTE` - Cloud-based inference only
*   `InferenceMode.LOCAL_FIRST` - Try local first, fallback to cloud
*   `InferenceMode.REMOTE_FIRST` - Try cloud first, fallback to local

To get a `cactusToken`, join our [Discord community](https://discord.gg/nPGWGxXSwr)
 and contact us.

### [Streaming Completions](https://cactuscompute.com/docs/kotlin#streaming-completions)

        val result = lm.generateCompletion(
        messages = listOf(ChatMessage("Tell me a story", "user")),
        params = CactusCompletionParams(maxTokens = 200),
            onToken = { token, tokenId ->
            print(token) // Print each token as it's generated
        }
    )

### [Available Models](https://cactuscompute.com/docs/kotlin#available-models)

You can get a list of available models:

    lm.getModels()

### [Function Calling](https://cactuscompute.com/docs/kotlin#function-calling)

    import com.cactus.models.ToolParameter
    import com.cactus.models.createTool
    
        val tools = listOf(
            createTool(
                name = "get_weather",
                description = "Get current weather for a location",
                parameters = mapOf(
                    "location" to ToolParameter(
                        type = "string",
                        description = "City name",
                        required = true
                    )
                )
            )
        )
    
        val result = lm.generateCompletion(
        messages = listOf(ChatMessage("What's the weather in New York?", "user")),
            params = CactusCompletionParams(
            maxTokens = 100,
                tools = tools
            )
        )

### [Vision (Multimodal)](https://cactuscompute.com/docs/kotlin#vision-multimodal)

    runBlocking {
        val lm = CactusLM()
    
        // Download and initialize a vision model
        val visionModel = lm.getModels().first { it.supports_vision }
        lm.downloadModel(visionModel.slug)
        lm.initializeModel(CactusInitParams(model = visionModel.slug))
    
        var streamingResponse = ""
    
        val result = lm.generateCompletion(
            messages = listOf(
                ChatMessage("You are a helpful AI assistant that can analyze images.", "system"),
                ChatMessage(
                    content = "What do you see in this image?",
                    role = "user",
                    images = listOf("/path/to/image.jpg")
                )
            ),
            params = CactusCompletionParams(maxTokens = 300),
            onToken = { token, _ ->
                streamingResponse += token
                print(token)
            }
        )
    
        println("\n\nFinal analysis: ${result?.response}")
    
        lm.unload()
    }

### [LLM API Reference](https://cactuscompute.com/docs/kotlin#llm-api-reference)

#### [CactusLM Class](https://cactuscompute.com/docs/kotlin#cactuslm-class)

*   `suspend fun downloadModel(model: String = "qwen3-0.6"): Boolean` - Download a model
*   `suspend fun initializeModel(params: CactusInitParams): Boolean` - Initialize model for inference
*   `suspend fun generateCompletion(messages: List<ChatMessage>, params: CactusCompletionParams = CactusCompletionParams(), onToken: CactusStreamingCallback? = null): CactusCompletionResult?` - Generate text completion with support for streaming and inference modes
*   `suspend fun generateEmbedding(text: String, modelName: String? = null): CactusEmbeddingResult?` - Generate text embeddings
*   `fun unload()` - Free model from memory
*   `suspend fun getModels(): List<CactusModel>` - Get available LLM models
*   `fun isLoaded(): Boolean` - Check if model is loaded

#### [Data Classes](https://cactuscompute.com/docs/kotlin#data-classes)

*   `CactusInitParams(model: String?, contextSize: Int?)` - Model initialization parameters
*   `CactusCompletionParams(temperature: Double, topK: Int, topP: Double, maxTokens: Int, stopSequences: List<String>, tools: List<Tool>?, mode: InferenceMode, cactusToken: String?, model: String?)` - Completion parameters
*   `ChatMessage(content: String, role: String, timestamp: Long?, images: List<String>)` - Chat message format
*   `CactusCompletionResult` - Contains response, timing metrics, and success status
*   `CactusEmbeddingResult(success: Boolean, embeddings: List<Double>, dimension: Int, errorMessage: String?)` - Embedding generation result
*   `InferenceMode` - Enum for inference modes (LOCAL, REMOTE, LOCAL\_FIRST, REMOTE\_FIRST)

[Tool Filtering](https://cactuscompute.com/docs/kotlin#tool-filtering)

-----------------------------------------------------------------------

The `ToolFilterService` enables intelligent filtering of tools to optimize function calling by selecting only the most relevant tools for a given user query.

### [Configuration](https://cactuscompute.com/docs/kotlin#configuration)

Configure tool filtering when creating a `CactusLM` instance:

    import com.cactus.CactusLM
    import com.cactus.services.ToolFilterConfig
    import com.cactus.services.ToolFilterStrategy
    
    // Enable with default settings (SIMPLE strategy, max 3 tools)
    val lm = CactusLM(
        enableToolFiltering = true,
        toolFilterConfig = ToolFilterConfig.simple(maxTools = 3)
    )
    
    // Custom configuration with SIMPLE strategy
    val lm = CactusLM(
        enableToolFiltering = true,
        toolFilterConfig = ToolFilterConfig(
            strategy = ToolFilterStrategy.SIMPLE,
            maxTools = 5,
            similarityThreshold = 0.3
        )
    )
    
    // Use SEMANTIC strategy for more accurate filtering
    val lm = CactusLM(
        enableToolFiltering = true,
        toolFilterConfig = ToolFilterConfig(
            strategy = ToolFilterStrategy.SEMANTIC,
            maxTools = 3,
            similarityThreshold = 0.5
        )
    )
    
    // Disable tool filtering
    val lm = CactusLM(enableToolFiltering = false)

### [Configuration Parameters](https://cactuscompute.com/docs/kotlin#configuration-parameters)

*   `strategy` - The filtering algorithm: `SIMPLE` (default, fast) or `SEMANTIC` (slower but more accurate)
*   `maxTools` - Maximum number of tools to pass to the model (default: null, meaning no limit)
*   `similarityThreshold` - Minimum score required for a tool to be included (default: 0.3)

[Embeddings](https://cactuscompute.com/docs/kotlin#embeddings)

---------------------------------------------------------------

The `CactusLM` class also provides text embedding generation capabilities for semantic similarity, search, and other NLP tasks.

### [Basic Usage](https://cactuscompute.com/docs/kotlin#basic-usage-1)

    import com.cactus.CactusLM
    import com.cactus.CactusInitParams
    import kotlinx.coroutines.runBlocking
    
    runBlocking {
        val lm = CactusLM()
        
        // Download and initialize a model (same as for completions)
        lm.downloadModel("qwen3-0.6")
        lm.initializeModel(CactusInitParams(model = "qwen3-0.6", contextSize = 2048))
    
        // Generate embeddings for a text
        val result = lm.generateEmbedding(
            text = "This is a sample text for embedding generation"
        )
    
        result?.let { embedding ->
            if (embedding.success) {
                println("Embedding dimension: ${embedding.dimension}")
                println("Embedding vector length: ${embedding.embeddings.size}")
            } else {
                println("Embedding generation failed: ${embedding.errorMessage}")
            }
        }
    
        lm.unload()
    }

### [Embedding API Reference](https://cactuscompute.com/docs/kotlin#embedding-api-reference)

#### [CactusLM Class (Embedding Methods)](https://cactuscompute.com/docs/kotlin#cactuslm-class-embedding-methods)

*   `suspend fun generateEmbedding(text: String, modelName: String? = null): CactusEmbeddingResult?` - Generate embeddings for the given text.
*   `suspend fun getModels(): List<CactusModel>` - Get a list of available models. Results are cached locally to reduce network requests.
*   `fun unload()` - Unload the current model and free resources.
*   `fun isLoaded(): Boolean` - Check if a model is currently loaded.

#### [Data Classes](https://cactuscompute.com/docs/kotlin#data-classes-1)

*   `CactusInitParams(model: String? = null, contextSize: Int? = null)` - Parameters for model initialization.
*   `CactusCompletionParams(model: String? = null, temperature: Double? = null, topK: Int? = null, topP: Double? = null, maxTokens: Int = 200, stopSequences: List<String> = listOf("<|im_end|>", "<end_of_turn>"), tools: List<CactusTool> = emptyList(), mode: InferenceMode = InferenceMode.LOCAL, cactusToken: String? = null)` - Parameters for text completion.
*   `CactusCompletionResult(success: Boolean, response: String? = null, timeToFirstTokenMs: Double? = null, totalTimeMs: Double? = null, tokensPerSecond: Double? = null, prefillTokens: Int? = null, decodeTokens: Int? = null, totalTokens: Int? = null, toolCalls: List<ToolCall>? = emptyList())` - The result of a text completion.
*   `CactusEmbeddingResult(success: Boolean, embeddings: List<Double> = listOf(), dimension: Int? = null, errorMessage: String? = null)` - The result of embedding generation.
*   `ChatMessage(content: String, role: String, timestamp: Long? = null)` - A chat message with role (e.g., "user", "assistant").
*   `CactusModel(created_at: String, slug: String, download_url: String, size_mb: Int, supports_tool_calling: Boolean, supports_vision: Boolean, name: String, isDownloaded: Boolean = false, quantization: Int = 8)` - Information about an available model.
*   `InferenceMode` - Enum for selecting inference mode (`LOCAL`, `REMOTE`, `LOCAL_FIRST`, `REMOTE_FIRST`).
*   `ToolCall(name: String, arguments: Map<String, String>)` - Represents a tool call returned by the model.
*   `CactusTool(type: String = "function", function: CactusFunction)` - Defines a tool that can be called by the model.
*   `CactusFunction(name: String, description: String, parameters: ToolParametersSchema)` - Function definition for a tool.
*   `ToolParametersSchema(type: String = "object", properties: Map<String, ToolParameter>, required: List<String>)` - Schema for tool parameters.
*   `ToolParameter(type: String, description: String, required: Boolean = false)` - A parameter definition for a tool.

#### [Helper Functions](https://cactuscompute.com/docs/kotlin#helper-functions)

*   `createTool(name: String, description: String, parameters: Map<String, ToolParameter>): CactusTool` - Helper function to create a tool with the correct schema.

[Speech-to-Text (STT)](https://cactuscompute.com/docs/kotlin#speech-to-text-stt)

---------------------------------------------------------------------------------

The `CactusSTT` class provides speech recognition capabilities using on-device models from **Whisper**.

### [Choosing a Transcription Provider](https://cactuscompute.com/docs/kotlin#choosing-a-transcription-provider)

You can select a transcription provider when initializing `CactusSTT`. The available providers are:

*   `TranscriptionProvider.WHISPER`: Uses Whisper for transcription.

    import com.cactus.CactusSTT
    import com.cactus.TranscriptionProvider
    
    // Initialize with the Whisper provider (default)
    val stt = CactusSTT() 

### [Basic Usage](https://cactuscompute.com/docs/kotlin#basic-usage-2)

    import com.cactus.CactusSTT
    import kotlinx.coroutines.runBlocking
    
    runBlocking {
        val stt = CactusSTT()
    
        // Download STT model (default: whisper-tiny)
        val downloadSuccess = stt.download("whisper-tiny)
        
        // Initialize the model
        val initSuccess = stt.init("whisper-tiny")
    
        // Transcribe from file
        val result = stt.transcribe(
            filePath = "/path/to/audio.wav",
            params = CactusTranscriptionParams()
        )
    
        result?.let { transcription ->
            if (transcription.success) {
                println("Transcribed: ${transcription.text}")
                println("Processing time: ${transcription.processingTime}ms")
            }
        }
    
        // Stop transcription
        stt.stop()
    }

### [Available Voice Models](https://cactuscompute.com/docs/kotlin#available-voice-models)

    // Get list of available voice models
    stt.getVoiceModels()
    
    // Check if model is downloaded
    stt.isModelDownloaded("whisper-tiny")

### [STT API Reference](https://cactuscompute.com/docs/kotlin#stt-api-reference)

#### [CactusSTT Class](https://cactuscompute.com/docs/kotlin#cactusstt-class)

*   `CactusSTT()` - Constructor for the STT service.
*   `suspend fun downloadModel(model: String = "whisper-tiny")` - Download an STT model (e.g., "whisper-tiny" or "whisper-base"). Defaults to last initialized model. Throws exception on failure.
*   `suspend fun initializeModel(params: CactusInitParams)` - Initialize an STT model for transcription using the model specified in params. Throws exception on failure.
*   `suspend fun transcribe(filePath: String, prompt: String = "<|startoftranscript|><|en|><|transcribe|><|notimestamps|>", params: CactusTranscriptionParams = CactusTranscriptionParams(), onToken: CactusStreamingCallback? = null, mode: TranscriptionMode = TranscriptionMode.LOCAL, apiKey: String? = null): CactusTranscriptionResult?` - Transcribe speech from an audio file. Supports streaming via the onToken callback and different transcription modes (local, remote, and fallbacks).
*   `suspend fun warmUpWispr(apiKey: String)` - Warms up the remote Wispr service for lower latency.
*   `fun isReady(): Boolean` - Check if the STT service is initialized and ready.
*   `suspend fun getVoiceModels(): List<VoiceModel>` - Get a list of available voice models. Results are cached locally to reduce network requests.
*   `suspend fun isModelDownloaded(modelName: String = "whisper-tiny"): Boolean` - Check if a specific model has been downloaded. Defaults to last initialized model.

#### [Data Classes](https://cactuscompute.com/docs/kotlin#data-classes-2)

*   `CactusInitParams(model: String? = null, contextSize: Int? = null)` - Parameters for model initialization (shared with CactusLM).
*   `CactusTranscriptionParams(model: String? = null, maxTokens: Int = 512, stopSequences: List<String> = listOf("<|im_end|>", "<end_of_turn>"))` - Parameters for controlling speech transcription.
*   `CactusTranscriptionResult(success: Boolean, text: String? = null, totalTimeMs: Double? = null)` - The result of a transcription.
*   `VoiceModel(created_at: String, slug: String, download_url: String, size_mb: Int, quantization: Int, isDownloaded: Boolean = false)` - Contains information about an available voice model.
*   `TranscriptionMode` - Enum for transcription mode (`LOCAL`, `REMOTE`, `LOCAL_FIRST`, `REMOTE_FIRST`).

[Platform-Specific Setup](https://cactuscompute.com/docs/kotlin#platform-specific-setup)

-----------------------------------------------------------------------------------------

### [Android](https://cactuscompute.com/docs/kotlin#android)

*   Works automatically - native libraries included
*   Requires API 24+ (Android 7.0)
*   ARM64 architecture supported

### [iOS](https://cactuscompute.com/docs/kotlin#ios)

*   Add the Cactus package dependency in Xcode
*   Requires iOS 12.0+
*   Supports ARM64 and Simulator ARM64

[Building the Library](https://cactuscompute.com/docs/kotlin#building-the-library)

-----------------------------------------------------------------------------------

To build the library from source:

    # Build the library and publish to localMaven
    ./build_library.sh

[Telemetry Setup (Optional)](https://cactuscompute.com/docs/kotlin#telemetry-setup-optional)

---------------------------------------------------------------------------------------------

Cactus comes with powerful built-in telemetry that lets you monitor your projects. Create a token on the [Cactus dashboard](https://cactuscompute.com/dashboard/telemetry-tokens)
 and get started with a one-line setup in your app:

    import com.cactus.services.CactusTelemetry
    
    // Initialize telemetry for usage analytics (optional)
    CactusTelemetry.setTelemetryToken("your_token_here")

[Example App](https://cactuscompute.com/docs/kotlin#example-app)

-----------------------------------------------------------------

Navigate to the example app and run it:

    cd kotlin/example
    
    # For desktop
    ./gradlew :composeApp:run
    
    # For Android/iOS - use Android Studio or Xcode

The example app demonstrates:

*   Model downloading and initialization
*   Text completion with streaming
*   Function calling
*   Speech-to-text transcription
*   Error handling and status management

[Performance Tips](https://cactuscompute.com/docs/kotlin#performance-tips)

---------------------------------------------------------------------------

1.  **Model Selection**: Choose smaller models for faster inference on mobile devices
2.  **Context Size**: Reduce context size for lower memory usage
3.  **Memory Management**: Always call `unload()` when done with models
4.  **Batch Processing**: Reuse initialized models for multiple completions
5.  **Model Caching**: Use `getModels()` for efficient model discovery - results are cached locally to reduce network requests

[Next Steps](https://cactuscompute.com/docs/kotlin#next-steps)

---------------------------------------------------------------

[### React Native SDK\
\
Learn about our React Native implementation](https://cactuscompute.com/docs/react-native)
[### Flutter SDK\
\
Learn about our Flutter implementation](https://cactuscompute.com/docs/flutter)
[### C++ SDK\
\
Native C++ development guide](https://cactuscompute.com/docs/cpp)
[### Join our discord!\
\
Ask questions and engage with the community](https://discord.gg/nPGWGxXSwr)

[React Native SDK\
\
Complete guide to using Cactus SDK in React Native applications](https://cactuscompute.com/docs/react-native)
[C++ SDK\
\
Complete guide to using Cactus SDK with C++ applications for native development](https://cactuscompute.com/docs/cpp)

### On this page

[Cactus Kotlin](https://cactuscompute.com/docs/kotlin#cactus-kotlin)
[Installation](https://cactuscompute.com/docs/kotlin#installation)
[Context Initialization (Required)](https://cactuscompute.com/docs/kotlin#context-initialization-required)
[Language Model (LLM)](https://cactuscompute.com/docs/kotlin#language-model-llm)
[Basic Usage](https://cactuscompute.com/docs/kotlin#basic-usage)
[Inference Modes](https://cactuscompute.com/docs/kotlin#inference-modes)
[Streaming Completions](https://cactuscompute.com/docs/kotlin#streaming-completions)
[Available Models](https://cactuscompute.com/docs/kotlin#available-models)
[Function Calling](https://cactuscompute.com/docs/kotlin#function-calling)
[Vision (Multimodal)](https://cactuscompute.com/docs/kotlin#vision-multimodal)
[LLM API Reference](https://cactuscompute.com/docs/kotlin#llm-api-reference)
[CactusLM Class](https://cactuscompute.com/docs/kotlin#cactuslm-class)
[Data Classes](https://cactuscompute.com/docs/kotlin#data-classes)
[Tool Filtering](https://cactuscompute.com/docs/kotlin#tool-filtering)
[Configuration](https://cactuscompute.com/docs/kotlin#configuration)
[Configuration Parameters](https://cactuscompute.com/docs/kotlin#configuration-parameters)
[Embeddings](https://cactuscompute.com/docs/kotlin#embeddings)
[Basic Usage](https://cactuscompute.com/docs/kotlin#basic-usage-1)
[Embedding API Reference](https://cactuscompute.com/docs/kotlin#embedding-api-reference)
[CactusLM Class (Embedding Methods)](https://cactuscompute.com/docs/kotlin#cactuslm-class-embedding-methods)
[Data Classes](https://cactuscompute.com/docs/kotlin#data-classes-1)
[Helper Functions](https://cactuscompute.com/docs/kotlin#helper-functions)
[Speech-to-Text (STT)](https://cactuscompute.com/docs/kotlin#speech-to-text-stt)
[Choosing a Transcription Provider](https://cactuscompute.com/docs/kotlin#choosing-a-transcription-provider)
[Basic Usage](https://cactuscompute.com/docs/kotlin#basic-usage-2)
[Available Voice Models](https://cactuscompute.com/docs/kotlin#available-voice-models)
[STT API Reference](https://cactuscompute.com/docs/kotlin#stt-api-reference)
[CactusSTT Class](https://cactuscompute.com/docs/kotlin#cactusstt-class)
[Data Classes](https://cactuscompute.com/docs/kotlin#data-classes-2)
[Platform-Specific Setup](https://cactuscompute.com/docs/kotlin#platform-specific-setup)
[Android](https://cactuscompute.com/docs/kotlin#android)
[iOS](https://cactuscompute.com/docs/kotlin#ios)
[Building the Library](https://cactuscompute.com/docs/kotlin#building-the-library)
[Telemetry Setup (Optional)](https://cactuscompute.com/docs/kotlin#telemetry-setup-optional)
[Example App](https://cactuscompute.com/docs/kotlin#example-app)
[Performance Tips](https://cactuscompute.com/docs/kotlin#performance-tips)
[Next Steps](https://cactuscompute.com/docs/kotlin#next-steps)

---

# React Native SDK

React Native SDK
================

Complete guide to using Cactus SDK in React Native applications

[Cactus React Native](https://cactuscompute.com/docs/react-native#cactus-react-native)

=======================================================================================

Official React Native SDK for Cactus, a framework for running AI locally in your apps.

[Installation](https://cactuscompute.com/docs/react-native#installation)

-------------------------------------------------------------------------

npmyarn

    npm install cactus-react-native react-native-nitro-modules

    yarn add cactus-react-native react-native-nitro-modules

[Quick Start](https://cactuscompute.com/docs/react-native#quick-start)

-----------------------------------------------------------------------

Get started with Cactus in just a few lines of code:

    import { CactusLM, type Message } from 'cactus-react-native';
    
    // Create a new instance
    const cactusLM = new CactusLM();
    
    // Download the model
    await cactusLM.download({
      onProgress: (progress) => console.log(`Download: ${Math.round(progress * 100)}%`)
    });
    
    // Generate a completion
    const messages: Message[] = [\
      { role: 'user', content: 'What is the capital of France?' }\
    ];
    
    const result = await cactusLM.complete({ messages });
    console.log(result.response); // "The capital of France is Paris."
    
    // Clean up resources
    await cactusLM.destroy();

**Using the React Hook:**

    import { useCactusLM } from 'cactus-react-native';
    
    const App = () => {
      const cactusLM = useCactusLM();
    
      useEffect(() => {
        // Download the model if not already available
        if (!cactusLM.isDownloaded) {
          cactusLM.download();
        }
      }, []);
    
      const handleGenerate = () => {
        // Generate a completion
        cactusLM.complete({
          messages: [{ role: 'user', content: 'Hello!' }],
        });
      };
    
      if (cactusLM.isDownloading) {
        return (
          <Text>
            Downloading model: {Math.round(cactusLM.downloadProgress * 100)}%
          </Text>
        );
      }
    
      return (
        <>
          <Button onPress={handleGenerate} title="Generate" />
          <Text>{cactusLM.completion}</Text>
        </>
      );
    };

[Language Model](https://cactuscompute.com/docs/react-native#language-model)

-----------------------------------------------------------------------------

### [Model Options](https://cactuscompute.com/docs/react-native#model-options)

Choose model quantization and NPU acceleration with Pro models.

    import { CactusLM } from 'cactus-react-native';
    
    // Use int4 for faster performance and smaller file size
    const cactusLM = new CactusLM({
      model: 'lfm2-vl-450m',
      options: {
        quantization: 'int4', // 'int4' or 'int8'
        pro: false
      }
    });
    
    // Use pro models for NPU acceleration
    const cactusPro = new CactusLM({
      model: 'lfm2-vl-450m',
      options: {
        quantization: 'int4',
        pro: true
      }
    });

### [Completion](https://cactuscompute.com/docs/react-native#completion)

Generate text responses from the model by providing a conversation history.

#### [Class](https://cactuscompute.com/docs/react-native#class)

    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('Token:', token) };
    
    const result = await cactusLM.complete({ messages, onToken });
    console.log('Completion result:', result);

#### [Hook](https://cactuscompute.com/docs/react-native#hook)

    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>
        </>
      );
    };

### [Vision](https://cactuscompute.com/docs/react-native#vision)

Vision allows you to pass images along with text prompts, enabling the model to analyze and understand visual content.

#### [Class](https://cactuscompute.com/docs/react-native#class-1)

    import { CactusLM, type Message } from 'cactus-react-native';
    
    // Vision-capable model
    const cactusLM = new CactusLM({ model: 'lfm2-vl-450m' });
    
    const messages: Message[] = [\
      {\
        role: 'user',\
        content: "What's in the image?",\
        images: ['path/to/your/image'],\
      },\
    ];
    
    const result = await cactusLM.complete({ messages });
    console.log('Response:', result.response);

#### [Hook](https://cactuscompute.com/docs/react-native#hook-1)

    import { useCactusLM, type Message } from 'cactus-react-native';
    
    const App = () => {
      // Vision-capable model
      const cactusLM = useCactusLM({ model: 'lfm2-vl-450m' });
    
      const handleAnalyze = async () => {
        const messages: Message[] = [\
          {\
            role: 'user',\
            content: "What's in the image?",\
            images: ['path/to/your/image'],\
          },\
        ];
    
        await cactusLM.complete({ messages });
      };
    
      return (
        <>
          <Button title="Analyze Image" onPress={handleAnalyze} />
          <Text>{cactusLM.completion}</Text>
        </>
      );
    };

### [Tool Calling](https://cactuscompute.com/docs/react-native#tool-calling)

Enable the model to generate function calls by defining available tools and their parameters.

#### [Class](https://cactuscompute.com/docs/react-native#class-2)

    import { CactusLM, type Message, type Tool } from 'cactus-react-native';
    
    const tools: Tool[] = [\
      {\
        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);
    console.log('Function calls:', result.functionCalls);

#### [Hook](https://cactuscompute.com/docs/react-native#hook-2)

    import { useCactusLM, type Message, type Tool } from 'cactus-react-native';
    
    const tools: Tool[] = [\
      {\
        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 result = await cactusLM.complete({ messages, tools });
        console.log('Response:', result.response);
        console.log('Function calls:', result.functionCalls);
      };
    
      return <Button title="Complete" onPress={handleComplete} />;
    };

### [RAG (Retrieval Augmented Generation)](https://cactuscompute.com/docs/react-native#rag-retrieval-augmented-generation)

RAG allows you to provide a corpus of documents that the model can reference during generation, enabling it to answer questions based on your data.

#### [Class](https://cactuscompute.com/docs/react-native#class-3)

    import { CactusLM, type Message } from 'cactus-react-native';
    
    const cactusLM = new CactusLM({
      corpusDir: 'path/to/your/corpus', // Directory containing .txt files
    });
    
    const messages: Message[] = [\
      { role: 'user', content: 'What information is in the documents?' },\
    ];
    
    const result = await cactusLM.complete({ messages });
    console.log(result.response);

#### [Hook](https://cactuscompute.com/docs/react-native#hook-3)

    import { useCactusLM, type Message } from 'cactus-react-native';
    
    const App = () => {
      const cactusLM = useCactusLM({
        corpusDir: 'path/to/your/corpus', // Directory containing .txt files
      });
    
      const handleAsk = async () => {
        const messages: Message[] = [\
          { role: 'user', content: 'What information is in the documents?' },\
        ];
    
        await cactusLM.complete({ messages });
      };
    
      return (
        <>
          <Button title="Ask Question" onPress={handleAsk} />
          <Text>{cactusLM.completion}</Text>
        </>
      );
    };

### [Tokenization](https://cactuscompute.com/docs/react-native#tokenization)

Convert text into tokens using the model's tokenizer.

#### [Class](https://cactuscompute.com/docs/react-native#class-4)

    import { CactusLM } from 'cactus-react-native';
    
    const cactusLM = new CactusLM();
    
    const result = await cactusLM.tokenize({ text: 'Hello, World!' });
    console.log('Token IDs:', result.tokens);

#### [Hook](https://cactuscompute.com/docs/react-native#hook-4)

    import { useCactusLM } from 'cactus-react-native';
    
    const App = () => {
      const cactusLM = useCactusLM();
    
      const handleTokenize = async () => {
        const result = await cactusLM.tokenize({ text: 'Hello, World!' });
        console.log('Token IDs:', result.tokens);
      };
    
      return <Button title="Tokenize" onPress={handleTokenize} />;
    };

### [Score Window](https://cactuscompute.com/docs/react-native#score-window)

Calculate perplexity scores for a window of tokens within a sequence.

#### [Class](https://cactuscompute.com/docs/react-native#class-5)

    import { CactusLM } from 'cactus-react-native';
    
    const cactusLM = new CactusLM();
    
    const tokens = [123, 456, 789, 101, 112];
    const result = await cactusLM.scoreWindow({
      tokens,
      start: 1,
      end: 3,
      context: 2
    });
    console.log('Score:', result.score);

#### [Hook](https://cactuscompute.com/docs/react-native#hook-5)

    import { useCactusLM } from 'cactus-react-native';
    
    const App = () => {
      const cactusLM = useCactusLM();
    
      const handleScoreWindow = async () => {
        const tokens = [123, 456, 789, 101, 112];
        const result = await cactusLM.scoreWindow({
          tokens,
          start: 1,
          end: 3,
          context: 2
        });
        console.log('Score:', result.score);
      };
    
      return <Button title="Score Window" onPress={handleScoreWindow} />;
    };

### [Embedding](https://cactuscompute.com/docs/react-native#embedding)

Convert text and images into numerical vector representations that capture semantic meaning, useful for similarity search and semantic understanding.

#### [Text Embedding](https://cactuscompute.com/docs/react-native#text-embedding)

##### [Class](https://cactuscompute.com/docs/react-native#class-6)

    import { CactusLM } from 'cactus-react-native';
    
    const cactusLM = new CactusLM();
    
    const result = await cactusLM.embed({ text: 'Hello, World!' });
    console.log('Embedding vector:', result.embedding);
    console.log('Embedding vector length:', result.embedding.length);

##### [Hook](https://cactuscompute.com/docs/react-native#hook-6)

    import { useCactusLM } from 'cactus-react-native';
    
    const App = () => {
      const cactusLM = useCactusLM();
    
      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);
      };
    
      return <Button title="Embed" onPress={handleEmbed} />;
    };

#### [Image Embedding](https://cactuscompute.com/docs/react-native#image-embedding)

##### [Class](https://cactuscompute.com/docs/react-native#class-7)

    import { CactusLM } from 'cactus-react-native';
    
    const cactusLM = new CactusLM({ model: 'lfm2-vl-450m' });
    
    const result = await cactusLM.imageEmbed({ imagePath: 'path/to/your/image.jpg' });
    console.log('Image embedding vector:', result.embedding);
    console.log('Embedding vector length:', result.embedding.length);

##### [Hook](https://cactuscompute.com/docs/react-native#hook-7)

    import { useCactusLM } from 'cactus-react-native';
    
    const App = () => {
      const cactusLM = useCactusLM({ model: 'lfm2-vl-450m' });
    
      const handleImageEmbed = async () => {
        const result = await cactusLM.imageEmbed({ imagePath: 'path/to/your/image.jpg' });
        console.log('Image embedding vector:', result.embedding);
        console.log('Embedding vector length:', result.embedding.length);
      };
    
      return <Button title="Embed Image" onPress={handleImageEmbed} />;
    };

### [Hybrid Mode (Cloud Fallback)](https://cactuscompute.com/docs/react-native#hybrid-mode-cloud-fallback)

The CactusLM supports a hybrid completion mode that falls back to a cloud-based LLM provider `OpenRouter` if local inference fails.

#### [Class](https://cactuscompute.com/docs/react-native#class-8)

    import { CactusLM, type Message } from 'cactus-react-native';
    
    const cactusLM = new CactusLM();
    
    const messages: Message[] = [\
      { role: 'user', content: 'Hello, World!' }\
    ];
    
    // Falls back to remote if local fails
    const result = await cactusLM.complete({
      messages,
      mode: 'hybrid'
    });

#### [Hook](https://cactuscompute.com/docs/react-native#hook-8)

    import { useCactusLM, type Message } from 'cactus-react-native';
    
    const App = () => {
      const cactusLM = useCactusLM();
    
      const handleComplete = async () => {
        const messages: Message[] = [\
          { role: 'user', content: 'Hello, World!' }\
        ];
    
        // Falls back to remote if local fails
        await cactusLM.complete({
          messages,
          mode: 'hybrid'
        });
      };
    
      return (
        <>
          <Button title="Complete" onPress={handleComplete} />
          <Text>{cactusLM.completion}</Text>
        </>
      );
    };

[Speech-to-Text (STT)](https://cactuscompute.com/docs/react-native#speech-to-text-stt)

---------------------------------------------------------------------------------------

The `CactusSTT` class provides audio transcription and audio embedding capabilities using Whisper models.

### [Transcription](https://cactuscompute.com/docs/react-native#transcription)

Transcribe audio to text with streaming support. Accepts either a file path or raw PCM audio samples.

#### [Class](https://cactuscompute.com/docs/react-native#class-9)

    import { CactusSTT } from 'cactus-react-native';
    
    const cactusSTT = new CactusSTT({ model: 'whisper-small' });
    
    await cactusSTT.init();
    
    // Transcribe from file path
    const result = await cactusSTT.transcribe({
      audio: 'path/to/audio.wav',
      onToken: (token) => console.log('Token:', token)
    });
    
    console.log('Transcription:', result.response);
    
    // Or transcribe from raw PCM samples
    const pcmSamples: number[] = [/* ... */];
    const result2 = await cactusSTT.transcribe({
      audio: pcmSamples,
      onToken: (token) => console.log('Token:', token)
    });
    
    console.log('Transcription:', result2.response);

#### [Hook](https://cactuscompute.com/docs/react-native#hook-9)

    import { useCactusSTT } from 'cactus-react-native';
    
    const App = () => {
      const cactusSTT = useCactusSTT({ model: 'whisper-small' });
    
      const handleTranscribe = async () => {
        // Transcribe from file path
        const result = await cactusSTT.transcribe({
          audio: 'path/to/audio.wav',
        });
        console.log('Transcription:', result.response);
    
        const pcmSamples: number[] = [/* ... */];
        const result2 = await cactusSTT.transcribe({
          audio: pcmSamples,
        });
        console.log('Transcription:', result2.response);
      };
    
      return (
        <>
          <Button onPress={handleTranscribe} title="Transcribe" />
          <Text>{cactusSTT.transcription}</Text>
        </>
      );
    };

### [Streaming Transcription](https://cactuscompute.com/docs/react-native#streaming-transcription)

Transcribe audio in real-time with incremental results.

#### [Class](https://cactuscompute.com/docs/react-native#class-10)

    import { CactusSTT } from 'cactus-react-native';
    
    const cactusSTT = new CactusSTT({ model: 'whisper-small' });
    
    await cactusSTT.streamTranscribeInit();
    
    const audioChunk: number[] = [/* PCM samples */];
    await cactusSTT.streamTranscribeInsert({ audio: audioChunk });
    
    const result = await cactusSTT.streamTranscribeProcess({
      options: { confirmationThreshold: 0.95 }
    });
    
    console.log('Confirmed:', result.confirmed);
    console.log('Pending:', result.pending);
    
    const final = await cactusSTT.streamTranscribeFinalize();
    await cactusSTT.streamTranscribeDestroy();

#### [Hook](https://cactuscompute.com/docs/react-native#hook-10)

    import { useCactusSTT } from 'cactus-react-native';
    
    const App = () => {
      const cactusSTT = useCactusSTT({ model: 'whisper-small' });
    
      const handleStream = async () => {
        await cactusSTT.streamTranscribeInit();
    
        const audioChunk: number[] = [/* PCM samples */];
        await cactusSTT.streamTranscribeInsert({ audio: audioChunk });
    
        await cactusSTT.streamTranscribeProcess();
      };
    
      return (
        <>
          <Button onPress={handleStream} title="Stream" />
          <Text>{cactusSTT.streamTranscribeConfirmed}</Text>
          <Text>{cactusSTT.streamTranscribePending}</Text>
        </>
      );
    };

### [Audio Embedding](https://cactuscompute.com/docs/react-native#audio-embedding)

Generate embeddings from audio files for audio understanding.

#### [Class](https://cactuscompute.com/docs/react-native#class-11)

    import { CactusSTT } from 'cactus-react-native';
    
    const cactusSTT = new CactusSTT();
    
    await cactusSTT.init();
    
    const result = await cactusSTT.audioEmbed({
      audioPath: 'path/to/audio.wav'
    });
    
    console.log('Audio embedding vector:', result.embedding);
    console.log('Embedding vector length:', result.embedding.length);

#### [Hook](https://cactuscompute.com/docs/react-native#hook-11)

    import { useCactusSTT } from 'cactus-react-native';
    
    const App = () => {
      const cactusSTT = useCactusSTT();
    
      const handleAudioEmbed = async () => {
        const result = await cactusSTT.audioEmbed({
          audioPath: 'path/to/audio.wav'
        });
        console.log('Audio embedding vector:', result.embedding);
        console.log('Embedding vector length:', result.embedding.length);
      };
    
      return <Button title="Embed Audio" onPress={handleAudioEmbed} />;
    };

[Vector Index](https://cactuscompute.com/docs/react-native#vector-index)

-------------------------------------------------------------------------

The `CactusIndex` class provides a vector database for storing and querying embeddings with metadata. Enabling similarity search and retrieval.

### [Creating and Initializing an Index](https://cactuscompute.com/docs/react-native#creating-and-initializing-an-index)

#### [Class](https://cactuscompute.com/docs/react-native#class-12)

    import { CactusIndex } from 'cactus-react-native';
    
    const cactusIndex = new CactusIndex('my-index', 1024);
    await cactusIndex.init();

#### [Hook](https://cactuscompute.com/docs/react-native#hook-12)

    import { useCactusIndex } from 'cactus-react-native';
    
    const App = () => {
      const cactusIndex = useCactusIndex({
        name: 'my-index',
        embeddingDim: 1024
      });
    
      const handleInit = async () => {
        await cactusIndex.init();
      };
    
      return <Button title="Initialize Index" onPress={handleInit} />
    };

### [Adding Documents](https://cactuscompute.com/docs/react-native#adding-documents)

Add documents with their embeddings and metadata to the index.

#### [Class](https://cactuscompute.com/docs/react-native#class-13)

    import { CactusIndex } from 'cactus-react-native';
    
    const cactusIndex = new CactusIndex('my-index', 1024);
    await cactusIndex.init();
    
    await cactusIndex.add({
      ids: [1, 2, 3],
      documents: ['First document', 'Second document', 'Third document'],
      embeddings: [\
        [0.1, 0.2, ...],\
        [0.3, 0.4, ...],\
        [0.5, 0.6, ...]\
      ],
      metadatas: ['metadata1', 'metadata2', 'metadata3']
    });

#### [Hook](https://cactuscompute.com/docs/react-native#hook-13)

    import { useCactusIndex } from 'cactus-react-native';
    
    const App = () => {
      const cactusIndex = useCactusIndex({
        name: 'my-index',
        embeddingDim: 1024
      });
    
      const handleAdd = async () => {
        await cactusIndex.add({
          ids: [1, 2, 3],
          documents: ['First document', 'Second document', 'Third document'],
          embeddings: [\
            [0.1, 0.2, ...],\
            [0.3, 0.4, ...],\
            [0.5, 0.6, ...]\
          ],
          metadatas: ['metadata1', 'metadata2', 'metadata3']
        });
      };
    
      return <Button title="Add Documents" onPress={handleAdd} />;
    };

### [Querying the Index](https://cactuscompute.com/docs/react-native#querying-the-index)

Search for similar documents using embedding vectors.

#### [Class](https://cactuscompute.com/docs/react-native#class-14)

    import { CactusIndex } from 'cactus-react-native';
    
    const cactusIndex = new CactusIndex('my-index', 1024);
    await cactusIndex.init();
    
    const result = await cactusIndex.query({
      embeddings: [[0.1, 0.2, ...]],
      options: {
        topK: 5,
        scoreThreshold: 0.7
      }
    });
    
    console.log('IDs:', result.ids);
    console.log('Scores:', result.scores);

#### [Hook](https://cactuscompute.com/docs/react-native#hook-14)

    import { useCactusIndex } from 'cactus-react-native';
    
    const App = () => {
      const cactusIndex = useCactusIndex({
        name: 'my-index',
        embeddingDim: 1024
      });
    
      const handleQuery = async () => {
        const result = await cactusIndex.query({
          embeddings: [[0.1, 0.2, ...]],
          options: {
            topK: 5,
            scoreThreshold: 0.7
          }
        });
        console.log('IDs:', result.ids);
        console.log('Scores:', result.scores);
      };
    
      return <Button title="Query Index" onPress={handleQuery} />;
    };

### [Retrieving Documents](https://cactuscompute.com/docs/react-native#retrieving-documents)

Get documents by their IDs.

#### [Class](https://cactuscompute.com/docs/react-native#class-15)

    import { CactusIndex } from 'cactus-react-native';
    
    const cactusIndex = new CactusIndex('my-index', 1024);
    await cactusIndex.init();
    
    const result = await cactusIndex.get({ ids: [1, 2, 3] });
    console.log('Documents:', result.documents);
    console.log('Metadatas:', result.metadatas);
    console.log('Embeddings:', result.embeddings);

#### [Hook](https://cactuscompute.com/docs/react-native#hook-15)

    import { useCactusIndex } from 'cactus-react-native';
    
    const App = () => {
      const cactusIndex = useCactusIndex({
        name: 'my-index',
        embeddingDim: 1024
      });
    
      const handleGet = async () => {
        const result = await cactusIndex.get({ ids: [1, 2, 3] });
        console.log('Documents:', result.documents);
        console.log('Metadatas:', result.metadatas);
        console.log('Embeddings:', result.embeddings);
      };
    
      return <Button title="Get Documents" onPress={handleGet} />;
    };

### [Deleting Documents](https://cactuscompute.com/docs/react-native#deleting-documents)

Mark documents as deleted by their IDs.

#### [Class](https://cactuscompute.com/docs/react-native#class-16)

    import { CactusIndex } from 'cactus-react-native';
    
    const cactusIndex = new CactusIndex('my-index', 1024);
    await cactusIndex.init();
    
    await cactusIndex.delete({ ids: [1, 2, 3] });

#### [Hook](https://cactuscompute.com/docs/react-native#hook-16)

    import { useCactusIndex } from 'cactus-react-native';
    
    const App = () => {
      const cactusIndex = useCactusIndex({
        name: 'my-index',
        embeddingDim: 1024
      });
    
      const handleDelete = async () => {
        await cactusIndex.delete({ ids: [1, 2, 3] });
      };
    
      return <Button title="Delete Documents" onPress={handleDelete} />;
    };

### [Compacting the Index](https://cactuscompute.com/docs/react-native#compacting-the-index)

Optimize the index by removing deleted documents and reorganizing data.

#### [Class](https://cactuscompute.com/docs/react-native#class-17)

    import { CactusIndex } from 'cactus-react-native';
    
    const cactusIndex = new CactusIndex('my-index', 1024);
    await cactusIndex.init();
    
    await cactusIndex.compact();

#### [Hook](https://cactuscompute.com/docs/react-native#hook-17)

    import { useCactusIndex } from 'cactus-react-native';
    
    const App = () => {
      const cactusIndex = useCactusIndex({
        name: 'my-index',
        embeddingDim: 1024
      });
    
      const handleCompact = async () => {
        await cactusIndex.compact();
      };
    
      return <Button title="Compact Index" onPress={handleCompact} />;
    };

[API Reference](https://cactuscompute.com/docs/react-native#api-reference)

---------------------------------------------------------------------------

### [CactusLM Class](https://cactuscompute.com/docs/react-native#cactuslm-class)

#### [Constructor](https://cactuscompute.com/docs/react-native#constructor)

**`new CactusLM(params?: CactusLMParams)`**

**Parameters:**

*   `model` - Model slug or absolute path to Cactus model (default: `'qwen3-0.6b'`).
*   `contextSize` - Context window size (default: `2048`).
*   `corpusDir` - Directory containing text files for RAG (default: `undefined`).
*   `options` - Model options for quantization and NPU acceleration:
    *   `quantization` - Quantization type: `'int4'` | `'int8'` (default: `'int4'`).
    *   `pro` - Enable NPU-accelerated models (default: `false`).

#### [Methods](https://cactuscompute.com/docs/react-native#methods)

**`download(params?: CactusLMDownloadParams): Promise<void>`**

Downloads the model. If the model is already downloaded, returns immediately with progress `1`. Throws an error if a download is already in progress.

**Parameters:**

*   `onProgress` - Callback for download progress (0-1).

**`init(): Promise<void>`**

Initializes the model and prepares it for inference. Safe to call multiple times (idempotent). Throws an error if the model is not downloaded yet.

**`complete(params: CactusLMCompleteParams): Promise<CactusLMCompleteResult>`**

Performs text completion with optional streaming and tool support. Automatically calls `init()` if not already initialized. Throws an error if a generation (completion or embedding) is already in progress.

**Parameters:**

*   `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`).
    *   `forceTools` - Force the model to call one of the provided tools (default: `false`).
*   `tools` - Array of `Tool` objects for function calling (default: `undefined`).
*   `onToken` - Callback for streaming tokens.
*   `mode` - Completion mode: `'local'` | `'hybrid'` (default: `'local'`)

**`tokenize(params: CactusLMTokenizeParams): Promise<CactusLMTokenizeResult>`**

Converts text into tokens using the model's tokenizer.

**Parameters:**

*   `text` - Text to tokenize.

**`scoreWindow(params: CactusLMScoreWindowParams): Promise<CactusLMScoreWindowResult>`**

Calculates perplexity scores for a window of tokens within a sequence.

**Parameters:**

*   `tokens` - Array of token IDs.
*   `start` - Start index of the window.
*   `end` - End index of the window.
*   `context` - Number of context tokens before the window.

**`embed(params: CactusLMEmbedParams): Promise<CactusLMEmbedResult>`**

Generates embeddings for the given text. Automatically calls `init()` if not already initialized. Throws an error if a generation (completion or embedding) is already in progress.

**Parameters:**

*   `text` - Text to embed.
*   `normalize` - Whether to normalize the embedding vector (default: `false`).

**`imageEmbed(params: CactusLMImageEmbedParams): Promise<CactusLMImageEmbedResult>`**

Generates embeddings for the given image. Requires a vision-capable model. Automatically calls `init()` if not already initialized. Throws an error if a generation (completion or embedding) is already in progress.

**Parameters:**

*   `imagePath` - Path to the image file.

**`stop(): Promise<void>`**

Stops ongoing generation.

**`reset(): Promise<void>`**

Resets the model's internal state, clearing any cached context. Automatically calls `stop()` first.

**`destroy(): Promise<void>`**

Releases all resources associated with the model. Automatically calls `stop()` first. Safe to call even if the model is not initialized.

**`getModels(): CactusModel[]`**

Returns available models.

### [useCactusLM Hook](https://cactuscompute.com/docs/react-native#usecactuslm-hook)

The `useCactusLM` hook manages a `CactusLM` instance with reactive state. When model parameters (`model`, `contextSize`, `corpusDir`, `options`) change, the hook creates a new instance and resets all state. The hook automatically cleans up resources when the component unmounts.

#### [State](https://cactuscompute.com/docs/react-native#state)

*   `completion: string` - Current generated text. Automatically accumulated during streaming. Cleared before each new completion and when calling `reset()` or `destroy()`.
*   `isGenerating: boolean` - Whether the model is currently generating (completion or embedding). Both operations share this flag.
*   `isInitializing: boolean` - Whether the model is initializing.
*   `isDownloaded: boolean` - Whether the model is downloaded locally. Automatically checked when the hook mounts or model changes.
*   `isDownloading: boolean` - Whether the model is being downloaded.
*   `downloadProgress: number` - Download progress (0-1). Reset to `0` after download completes.
*   `error: string | null` - Last error message from any operation, or `null` if there is no error. Cleared before starting new operations.

#### [Methods](https://cactuscompute.com/docs/react-native#methods-1)

*   `download(params?: CactusLMDownloadParams): Promise<void>` - Downloads the model. Updates `isDownloading` and `downloadProgress` state during download. Sets `isDownloaded` to `true` on success.
*   `init(): Promise<void>` - Initializes the model for inference. Sets `isInitializing` to `true` during initialization.
*   `complete(params: CactusLMCompleteParams): Promise<CactusLMCompleteResult>` - Generates text completions. Automatically accumulates tokens in the `completion` state during streaming. Sets `isGenerating` to `true` while generating. Clears `completion` before starting.
*   `tokenize(params: CactusLMTokenizeParams): Promise<CactusLMTokenizeResult>` - Converts text into tokens. Sets `isGenerating` to `true` during operation.
*   `scoreWindow(params: CactusLMScoreWindowParams): Promise<CactusLMScoreWindowResult>` - Calculates perplexity scores for a window of tokens. Sets `isGenerating` to `true` during operation.
*   `embed(params: CactusLMEmbedParams): Promise<CactusLMEmbedResult>` - Generates embeddings for the given text. Sets `isGenerating` to `true` during operation.
*   `imageEmbed(params: CactusLMImageEmbedParams): Promise<CactusLMImageEmbedResult>` - Generates embeddings for the given image. Sets `isGenerating` to `true` while generating.
*   `stop(): Promise<void>` - Stops ongoing generation. Clears any errors.
*   `reset(): Promise<void>` - Resets the model's internal state, clearing cached context. Also clears the `completion` state.
*   `destroy(): Promise<void>` - Releases all resources associated with the model. Clears the `completion` state. Automatically called when the component unmounts.
*   `getModels(): CactusModel[]` - Returns available models.

### [CactusSTT Class](https://cactuscompute.com/docs/react-native#cactusstt-class)

#### [Constructor](https://cactuscompute.com/docs/react-native#constructor-1)

**`new CactusSTT(params?: CactusSTTParams)`**

**Parameters:**

*   `model` - Model slug or absolute path to Cactus model (default: `'whisper-small'`).
*   `contextSize` - Context window size (default: `2048`).
*   `options` - Model options for quantization and NPU acceleration:
    *   `quantization` - Quantization type: `'int4'` | `'int8'` (default: `'int4'`).
    *   `pro` - Enable NPU-accelerated models (default: `false`).

#### [Methods](https://cactuscompute.com/docs/react-native#methods-2)

**`download(params?: CactusSTTDownloadParams): Promise<void>`**

Downloads the model. If the model is already downloaded, returns immediately with progress `1`. Throws an error if a download is already in progress.

**Parameters:**

*   `onProgress` - Callback for download progress (0-1).

**`init(): Promise<void>`**

Initializes the model and prepares it for inference. Safe to call multiple times (idempotent). Throws an error if the model is not downloaded yet.

**`transcribe(params: CactusSTTTranscribeParams): Promise<CactusSTTTranscribeResult>`**

Transcribes audio to text with optional streaming support. Accepts either a file path or raw PCM audio samples. Automatically calls `init()` if not already initialized. Throws an error if a generation is already in progress.

**Parameters:**

*   `audio` - Path to the audio file or raw PCM samples.
*   `prompt` - Optional prompt to guide transcription (default: `'<|startoftranscript|><|en|><|transcribe|><|notimestamps|>'`).
*   `options` - Transcription 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`).
*   `onToken` - Callback for streaming tokens.

**`audioEmbed(params: CactusSTTAudioEmbedParams): Promise<CactusSTTAudioEmbedResult>`**

Generates embeddings for the given audio file. Automatically calls `init()` if not already initialized. Throws an error if a generation is already in progress.

**Parameters:**

*   `audioPath` - Path to the audio file.

**`streamTranscribeInit(): Promise<void>`**

Initializes a streaming transcription session. Automatically calls `init()` if not already initialized.

**`streamTranscribeInsert(params: CactusSTTStreamTranscribeInsertParams): Promise<void>`**

Inserts PCM audio samples into the streaming buffer.

**Parameters:**

*   `audio` - Array of PCM audio samples.

**`streamTranscribeProcess(params?: CactusSTTStreamTranscribeProcessParams): Promise<CactusSTTStreamTranscribeProcessResult>`**

Processes accumulated audio and returns incremental transcription results.

**Parameters:**

*   `options` - Processing options:
    *   `confirmationThreshold` - Confidence threshold for confirming text.

**`streamTranscribeFinalize(): Promise<CactusSTTStreamTranscribeFinalizeResult>`**

Finalizes the streaming session and returns remaining transcription text.

**`streamTranscribeDestroy(): Promise<void>`**

Destroys the streaming session and releases resources.

**`stop(): Promise<void>`**

Stops ongoing transcription or embedding generation.

**`reset(): Promise<void>`**

Resets the model's internal state. Automatically calls `stop()` first.

**`destroy(): Promise<void>`**

Releases all resources associated with the model. Automatically calls `stop()` first. Safe to call even if the model is not initialized.

**`getModels(): CactusModel[]`**

Returns available speech-to-text models.

### [useCactusSTT Hook](https://cactuscompute.com/docs/react-native#usecactusstt-hook)

The `useCactusSTT` hook manages a `CactusSTT` instance with reactive state. When model parameters (`model`, `contextSize`, `options`) change, the hook creates a new instance and resets all state. The hook automatically cleans up resources when the component unmounts.

#### [State](https://cactuscompute.com/docs/react-native#state-1)

*   `transcription: string` - Current transcription text. Automatically accumulated during streaming. Cleared before each new transcription and when calling `reset()` or `destroy()`.
*   `streamTranscribeConfirmed: string` - Accumulated confirmed text from streaming transcription.
*   `streamTranscribePending: string` - Current pending text from streaming transcription.
*   `isGenerating: boolean` - Whether the model is currently generating (transcription or embedding). Both operations share this flag.
*   `isStreamTranscribing: boolean` - Whether a streaming transcription session is active.
*   `isInitializing: boolean` - Whether the model is initializing.
*   `isDownloaded: boolean` - Whether the model is downloaded locally. Automatically checked when the hook mounts or model changes.
*   `isDownloading: boolean` - Whether the model is being downloaded.
*   `downloadProgress: number` - Download progress (0-1). Reset to `0` after download completes.
*   `error: string | null` - Last error message from any operation, or `null` if there is no error. Cleared before starting new operations.

#### [Methods](https://cactuscompute.com/docs/react-native#methods-3)

*   `download(params?: CactusSTTDownloadParams): Promise<void>` - Downloads the model. Updates `isDownloading` and `downloadProgress` state during download. Sets `isDownloaded` to `true` on success.
*   `init(): Promise<void>` - Initializes the model for inference. Sets `isInitializing` to `true` during initialization.
*   `transcribe(params: CactusSTTTranscribeParams): Promise<CactusSTTTranscribeResult>` - Transcribes audio to text. Automatically accumulates tokens in the `transcription` state during streaming. Sets `isGenerating` to `true` while generating. Clears `transcription` before starting.
*   `audioEmbed(params: CactusSTTAudioEmbedParams): Promise<CactusSTTAudioEmbedResult>` - Generates embeddings for the given audio. Sets `isGenerating` to `true` during operation.
*   `streamTranscribeInit(): Promise<void>` - Initializes a streaming transcription session. Sets `isStreamTranscribing` to `true`.
*   `streamTranscribeInsert(params: CactusSTTStreamTranscribeInsertParams): Promise<void>` - Inserts audio chunks into the streaming buffer.
*   `streamTranscribeProcess(params?: CactusSTTStreamTranscribeProcessParams): Promise<CactusSTTStreamTranscribeProcessResult>` - Processes audio and returns results. Automatically accumulates confirmed text in `streamTranscribeConfirmed` and updates `streamTranscribePending`.
*   `streamTranscribeFinalize(): Promise<CactusSTTStreamTranscribeFinalizeResult>` - Finalizes streaming and returns remaining text.
*   `streamTranscribeDestroy(): Promise<void>` - Destroys the streaming session. Sets `isStreamTranscribing` to `false`.
*   `stop(): Promise<void>` - Stops ongoing generation. Clears any errors.
*   `reset(): Promise<void>` - Resets the model's internal state. Also clears the `transcription` state.
*   `destroy(): Promise<void>` - Releases all resources associated with the model. Clears the `transcription` state. Automatically called when the component unmounts.
*   `getModels(): CactusModel[]` - Returns available speech-to-text models.

### [CactusIndex Class](https://cactuscompute.com/docs/react-native#cactusindex-class)

#### [Constructor](https://cactuscompute.com/docs/react-native#constructor-2)

**`new CactusIndex(name: string, embeddingDim: number)`**

**Parameters:**

*   `name` - Name of the index.
*   `embeddingDim` - Dimension of the embedding vectors.

#### [Methods](https://cactuscompute.com/docs/react-native#methods-4)

**`init(): Promise<void>`**

Initializes the index and prepares it for operations. Must be called before using any other methods.

**`add(params: CactusIndexAddParams): Promise<void>`**

Adds documents with their embeddings and metadata to the index.

**Parameters:**

*   `ids` - Array of document IDs.
*   `documents` - Array of document texts.
*   `embeddings` - Array of embedding vectors (each vector must match `embeddingDim`).
*   `metadatas` - Optional array of metadata strings.

**`query(params: CactusIndexQueryParams): Promise<CactusIndexQueryResult>`**

Searches for similar documents using embedding vectors.

**Parameters:**

*   `embeddings` - Array of query embedding vectors.
*   `options` - Query options:
    *   `topK` - Number of top results to return (default: 10).
    *   `scoreThreshold` - Minimum similarity score threshold (default: -1.0).

**`get(params: CactusIndexGetParams): Promise<CactusIndexGetResult>`**

Retrieves documents by their IDs.

**Parameters:**

*   `ids` - Array of document IDs to retrieve.

**`delete(params: CactusIndexDeleteParams): Promise<void>`**

Deletes documents from the index by their IDs.

**Parameters:**

*   `ids` - Array of document IDs to delete.

**`compact(): Promise<void>`**

Optimizes the index by removing deleted documents and reorganizing data for better performance. Call after a series of deletions.

**`destroy(): Promise<void>`**

Releases all resources associated with the index from memory.

### [useCactusIndex Hook](https://cactuscompute.com/docs/react-native#usecactusindex-hook)

The `useCactusIndex` hook manages a `CactusIndex` instance with reactive state. When index parameters (`name` or `embeddingDim`) change, the hook creates a new instance and resets all state. The hook automatically cleans up resources when the component unmounts.

#### [State](https://cactuscompute.com/docs/react-native#state-2)

*   `isInitializing: boolean` - Whether the index is initializing.
*   `isProcessing: boolean` - Whether the index is processing an operation (add, query, get, delete, or compact).
*   `error: string | null` - Last error message from any operation, or `null` if there is no error. Cleared before starting new operations.

#### [Methods](https://cactuscompute.com/docs/react-native#methods-5)

*   `init(): Promise<void>` - Initializes the index. Sets `isInitializing` to `true` during initialization.
*   `add(params: CactusIndexAddParams): Promise<void>` - Adds documents to the index. Sets `isProcessing` to `true` during operation.
*   `query(params: CactusIndexQueryParams): Promise<CactusIndexQueryResult>` - Searches for similar documents. Sets `isProcessing` to `true` during operation.
*   `get(params: CactusIndexGetParams): Promise<CactusIndexGetResult>` - Retrieves documents by IDs. Sets `isProcessing` to `true` during operation.
*   `delete(params: CactusIndexDeleteParams): Promise<void>` - Deletes documents. Sets `isProcessing` to `true` during operation.
*   `compact(): Promise<void>` - Optimizes the index. Sets `isProcessing` to `true` during operation.
*   `destroy(): Promise<void>` - Releases all resources. Automatically called when the component unmounts.

[Type Definitions](https://cactuscompute.com/docs/react-native#type-definitions)

---------------------------------------------------------------------------------

### [CactusLMParams](https://cactuscompute.com/docs/react-native#cactuslmparams)

    interface CactusLMParams {
      model?: string;
      contextSize?: number;
      corpusDir?: string;
      options?: ModelOptions;
    }

### [CactusLMDownloadParams](https://cactuscompute.com/docs/react-native#cactuslmdownloadparams)

    interface CactusLMDownloadParams {
      onProgress?: (progress: number) => void;
    }

### [Message](https://cactuscompute.com/docs/react-native#message)

    interface Message {
      role: 'user' | 'assistant' | 'system';
      content?: string;
      images?: string[];
    }

### [CompleteOptions](https://cactuscompute.com/docs/react-native#completeoptions)

    interface CompleteOptions {
      temperature?: number;
      topP?: number;
      topK?: number;
      maxTokens?: number;
      stopSequences?: string[];
      forceTools?: boolean;
    }

### [Tool](https://cactuscompute.com/docs/react-native#tool)

    interface Tool {
      name: string;
      description: string;
      parameters: {
        type: 'object';
        properties: {
          [key: string]: {
            type: string;
            description: string;
          };
        };
        required: string[];
      };
    }

### [CactusLMCompleteParams](https://cactuscompute.com/docs/react-native#cactuslmcompleteparams)

    interface CactusLMCompleteParams {
      messages: Message[];
      options?: CompleteOptions;
      tools?: Tool[];
      onToken?: (token: string) => void;
      mode?: 'local' | 'hybrid';
    }

### [CactusLMCompleteResult](https://cactuscompute.com/docs/react-native#cactuslmcompleteresult)

    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;
    }

### [CactusLMTokenizeParams](https://cactuscompute.com/docs/react-native#cactuslmtokenizeparams)

    interface CactusLMTokenizeParams {
      text: string;
    }

### [CactusLMTokenizeResult](https://cactuscompute.com/docs/react-native#cactuslmtokenizeresult)

    interface CactusLMTokenizeResult {
      tokens: number[];
    }

### [CactusLMScoreWindowParams](https://cactuscompute.com/docs/react-native#cactuslmscorewindowparams)

    interface CactusLMScoreWindowParams {
      tokens: number[];
      start: number;
      end: number;
      context: number;
    }

### [CactusLMScoreWindowResult](https://cactuscompute.com/docs/react-native#cactuslmscorewindowresult)

    interface CactusLMScoreWindowResult {
      score: number;
    }

### [CactusLMEmbedParams](https://cactuscompute.com/docs/react-native#cactuslmembedparams)

    interface CactusLMEmbedParams {
      text: string;
      normalize?: boolean;
    }

### [CactusLMEmbedResult](https://cactuscompute.com/docs/react-native#cactuslmembedresult)

    interface CactusLMEmbedResult {
      embedding: number[];
    }

### [CactusLMImageEmbedParams](https://cactuscompute.com/docs/react-native#cactuslmimageembedparams)

    interface CactusLMImageEmbedParams {
      imagePath: string;
    }

### [CactusLMImageEmbedResult](https://cactuscompute.com/docs/react-native#cactuslmimageembedresult)

    interface CactusLMImageEmbedResult {
      embedding: number[];
    }

### [CactusModel](https://cactuscompute.com/docs/react-native#cactusmodel)

    interface CactusModel {
      completion: boolean;
      tools: boolean;
      vision: boolean;
      embed: boolean;
      speech: boolean;
      quantization: {
        int4: {
          sizeMb: number;
          url: string;
          pro?: {
            apple: string;
          };
        };
        int8: {
          sizeMb: number;
          url: string;
          pro?: {
            apple: string;
          };
        };
      };
    }

### [ModelOptions](https://cactuscompute.com/docs/react-native#modeloptions)

    interface ModelOptions {
      quantization: 'int4' | 'int8';
      pro: boolean;
    }

### [CactusSTTParams](https://cactuscompute.com/docs/react-native#cactussttparams)

    interface CactusSTTParams {
      model?: string;
      contextSize?: number;
      options?: ModelOptions;
    }

### [CactusSTTDownloadParams](https://cactuscompute.com/docs/react-native#cactussttdownloadparams)

    interface CactusSTTDownloadParams {
      onProgress?: (progress: number) => void;
    }

### [TranscribeOptions](https://cactuscompute.com/docs/react-native#transcribeoptions)

    interface TranscribeOptions {
      temperature?: number;
      topP?: number;
      topK?: number;
      maxTokens?: number;
      stopSequences?: string[];
    }

### [CactusSTTTranscribeParams](https://cactuscompute.com/docs/react-native#cactusstttranscribeparams)

    interface CactusSTTTranscribeParams {
      audio: string | number[];
      prompt?: string;
      options?: TranscribeOptions;
      onToken?: (token: string) => void;
    }

### [CactusSTTTranscribeResult](https://cactuscompute.com/docs/react-native#cactusstttranscriberesult)

    interface CactusSTTTranscribeResult {
      success: boolean;
      response: string;
      timeToFirstTokenMs: number;
      totalTimeMs: number;
      tokensPerSecond: number;
      prefillTokens: number;
      decodeTokens: number;
      totalTokens: number;
    }

### [CactusSTTAudioEmbedParams](https://cactuscompute.com/docs/react-native#cactussttaudioembedparams)

    interface CactusSTTAudioEmbedParams {
      audioPath: string;
    }

### [CactusSTTAudioEmbedResult](https://cactuscompute.com/docs/react-native#cactussttaudioembedresult)

    interface CactusSTTAudioEmbedResult {
      embedding: number[];
    }

### [CactusSTTStreamTranscribeInsertParams](https://cactuscompute.com/docs/react-native#cactussttstreamtranscribeinsertparams)

    interface CactusSTTStreamTranscribeInsertParams {
      audio: number[];
    }

### [StreamTranscribeProcessOptions](https://cactuscompute.com/docs/react-native#streamtranscribeprocessoptions)

    interface StreamTranscribeProcessOptions {
      confirmationThreshold?: number;
    }

### [CactusSTTStreamTranscribeProcessParams](https://cactuscompute.com/docs/react-native#cactussttstreamtranscribeprocessparams)

    interface CactusSTTStreamTranscribeProcessParams {
      options?: StreamTranscribeProcessOptions;
    }

### [CactusSTTStreamTranscribeProcessResult](https://cactuscompute.com/docs/react-native#cactussttstreamtranscribeprocessresult)

    interface CactusSTTStreamTranscribeProcessResult {
      success: boolean;
      confirmed: string;
      pending: string;
    }

### [CactusSTTStreamTranscribeFinalizeResult](https://cactuscompute.com/docs/react-native#cactussttstreamtranscribefinalizeresult)

    interface CactusSTTStreamTranscribeFinalizeResult {
      success: boolean;
      confirmed: string;
    }

### [CactusIndexParams](https://cactuscompute.com/docs/react-native#cactusindexparams)

    interface CactusIndexParams {
      name: string;
      embeddingDim: number;
    }

### [CactusIndexAddParams](https://cactuscompute.com/docs/react-native#cactusindexaddparams)

    interface CactusIndexAddParams {
      ids: number[];
      documents: string[];
      embeddings: number[][];
      metadatas?: string[];
    }

### [CactusIndexGetParams](https://cactuscompute.com/docs/react-native#cactusindexgetparams)

    interface CactusIndexGetParams {
      ids: number[];
    }

### [CactusIndexGetResult](https://cactuscompute.com/docs/react-native#cactusindexgetresult)

    interface CactusIndexGetResult {
      documents: string[];
      metadatas: string[];
      embeddings: number[][];
    }

### [IndexQueryOptions](https://cactuscompute.com/docs/react-native#indexqueryoptions)

    interface IndexQueryOptions {
      topK?: number;
      scoreThreshold?: number;
    }

### [CactusIndexQueryParams](https://cactuscompute.com/docs/react-native#cactusindexqueryparams)

    interface CactusIndexQueryParams {
      embeddings: number[][];
      options?: IndexQueryOptions;
    }

### [CactusIndexQueryResult](https://cactuscompute.com/docs/react-native#cactusindexqueryresult)

    interface CactusIndexQueryResult {
      ids: number[][];
      scores: number[][];
    }

### [CactusIndexDeleteParams](https://cactuscompute.com/docs/react-native#cactusindexdeleteparams)

    interface CactusIndexDeleteParams {
      ids: number[];
    }

[Configuration](https://cactuscompute.com/docs/react-native#configuration)

---------------------------------------------------------------------------

### [Telemetry](https://cactuscompute.com/docs/react-native#telemetry)

Cactus offers powerful telemetry for all your projects. Create a token on the [Cactus dashboard](https://www.cactuscompute.com/dashboard)
.

    import { CactusConfig } from 'cactus-react-native';
    
    // Enable Telemetry for your project
    CactusConfig.telemetryToken = 'your-telemetry-token-here';
    
    // Disable telemetry
    CactusConfig.isTelemetryEnabled = false;

### [Hybrid Mode](https://cactuscompute.com/docs/react-native#hybrid-mode)

Enable cloud fallback.

    import { CactusConfig } from 'cactus-react-native';
    
    // Set your Cactus token for hybrid mode
    CactusConfig.cactusToken = 'your-cactus-token-here';

### [Cactus Pro](https://cactuscompute.com/docs/react-native#cactus-pro)

Enable NPU-accelerated models for enhanced performance.

    import { CactusConfig } from 'cactus-react-native';
    
    // Set your Cactus Pro key
    CactusConfig.cactusProKey = 'your-cactus-pro-key-here';

[Performance Tips](https://cactuscompute.com/docs/react-native#performance-tips)

---------------------------------------------------------------------------------

*   **Model Selection** - Choose smaller models for faster inference on mobile devices.
*   **Context Size** - Reduce the context size to lower memory usage.
*   **Memory Management** - Always call `destroy()` when you're done with models to free up resources.

[Example App](https://cactuscompute.com/docs/react-native#example-app)

-----------------------------------------------------------------------

Check out [our example app](https://github.com/cactus-compute/cactus-react-native/tree/main/example)
 for a complete React Native implementation with examples of completion, tool calling, and embedding.

[Next Steps](https://cactuscompute.com/docs/react-native#next-steps)

---------------------------------------------------------------------

[### Flutter SDK\
\
Learn about our Flutter implementation.](https://cactuscompute.com/docs/flutter)
[### Kotlin Multiplatform SDK\
\
Learn about our KMP implementation.](https://cactuscompute.com/docs/kotlin)
[### C++ SDK\
\
Native C++ development guide.](https://cactuscompute.com/docs/cpp)
[### Join our discord!\
\
Ask questions and engage with the community.](https://discord.gg/nPGWGxXSwr)

[Flutter SDK\
\
Complete guide to using Cactus SDK in Flutter applications](https://cactuscompute.com/docs/flutter)
[Kotlin Multiplatform SDK\
\
Complete guide to using Cactus SDK in Kotlin applications](https://cactuscompute.com/docs/kotlin)

### On this page

[Cactus React Native](https://cactuscompute.com/docs/react-native#cactus-react-native)
[Installation](https://cactuscompute.com/docs/react-native#installation)
[Quick Start](https://cactuscompute.com/docs/react-native#quick-start)
[Language Model](https://cactuscompute.com/docs/react-native#language-model)
[Model Options](https://cactuscompute.com/docs/react-native#model-options)
[Completion](https://cactuscompute.com/docs/react-native#completion)
[Class](https://cactuscompute.com/docs/react-native#class)
[Hook](https://cactuscompute.com/docs/react-native#hook)
[Vision](https://cactuscompute.com/docs/react-native#vision)
[Class](https://cactuscompute.com/docs/react-native#class-1)
[Hook](https://cactuscompute.com/docs/react-native#hook-1)
[Tool Calling](https://cactuscompute.com/docs/react-native#tool-calling)
[Class](https://cactuscompute.com/docs/react-native#class-2)
[Hook](https://cactuscompute.com/docs/react-native#hook-2)
[RAG (Retrieval Augmented Generation)](https://cactuscompute.com/docs/react-native#rag-retrieval-augmented-generation)
[Class](https://cactuscompute.com/docs/react-native#class-3)
[Hook](https://cactuscompute.com/docs/react-native#hook-3)
[Tokenization](https://cactuscompute.com/docs/react-native#tokenization)
[Class](https://cactuscompute.com/docs/react-native#class-4)
[Hook](https://cactuscompute.com/docs/react-native#hook-4)
[Score Window](https://cactuscompute.com/docs/react-native#score-window)
[Class](https://cactuscompute.com/docs/react-native#class-5)
[Hook](https://cactuscompute.com/docs/react-native#hook-5)
[Embedding](https://cactuscompute.com/docs/react-native#embedding)
[Text Embedding](https://cactuscompute.com/docs/react-native#text-embedding)
[Class](https://cactuscompute.com/docs/react-native#class-6)
[Hook](https://cactuscompute.com/docs/react-native#hook-6)
[Image Embedding](https://cactuscompute.com/docs/react-native#image-embedding)
[Class](https://cactuscompute.com/docs/react-native#class-7)
[Hook](https://cactuscompute.com/docs/react-native#hook-7)
[Hybrid Mode (Cloud Fallback)](https://cactuscompute.com/docs/react-native#hybrid-mode-cloud-fallback)
[Class](https://cactuscompute.com/docs/react-native#class-8)
[Hook](https://cactuscompute.com/docs/react-native#hook-8)
[Speech-to-Text (STT)](https://cactuscompute.com/docs/react-native#speech-to-text-stt)
[Transcription](https://cactuscompute.com/docs/react-native#transcription)
[Class](https://cactuscompute.com/docs/react-native#class-9)
[Hook](https://cactuscompute.com/docs/react-native#hook-9)
[Streaming Transcription](https://cactuscompute.com/docs/react-native#streaming-transcription)
[Class](https://cactuscompute.com/docs/react-native#class-10)
[Hook](https://cactuscompute.com/docs/react-native#hook-10)
[Audio Embedding](https://cactuscompute.com/docs/react-native#audio-embedding)
[Class](https://cactuscompute.com/docs/react-native#class-11)
[Hook](https://cactuscompute.com/docs/react-native#hook-11)
[Vector Index](https://cactuscompute.com/docs/react-native#vector-index)
[Creating and Initializing an Index](https://cactuscompute.com/docs/react-native#creating-and-initializing-an-index)
[Class](https://cactuscompute.com/docs/react-native#class-12)
[Hook](https://cactuscompute.com/docs/react-native#hook-12)
[Adding Documents](https://cactuscompute.com/docs/react-native#adding-documents)
[Class](https://cactuscompute.com/docs/react-native#class-13)
[Hook](https://cactuscompute.com/docs/react-native#hook-13)
[Querying the Index](https://cactuscompute.com/docs/react-native#querying-the-index)
[Class](https://cactuscompute.com/docs/react-native#class-14)
[Hook](https://cactuscompute.com/docs/react-native#hook-14)
[Retrieving Documents](https://cactuscompute.com/docs/react-native#retrieving-documents)
[Class](https://cactuscompute.com/docs/react-native#class-15)
[Hook](https://cactuscompute.com/docs/react-native#hook-15)
[Deleting Documents](https://cactuscompute.com/docs/react-native#deleting-documents)
[Class](https://cactuscompute.com/docs/react-native#class-16)
[Hook](https://cactuscompute.com/docs/react-native#hook-16)
[Compacting the Index](https://cactuscompute.com/docs/react-native#compacting-the-index)
[Class](https://cactuscompute.com/docs/react-native#class-17)
[Hook](https://cactuscompute.com/docs/react-native#hook-17)
[API Reference](https://cactuscompute.com/docs/react-native#api-reference)
[CactusLM Class](https://cactuscompute.com/docs/react-native#cactuslm-class)
[Constructor](https://cactuscompute.com/docs/react-native#constructor)
[Methods](https://cactuscompute.com/docs/react-native#methods)
[useCactusLM Hook](https://cactuscompute.com/docs/react-native#usecactuslm-hook)
[State](https://cactuscompute.com/docs/react-native#state)
[Methods](https://cactuscompute.com/docs/react-native#methods-1)
[CactusSTT Class](https://cactuscompute.com/docs/react-native#cactusstt-class)
[Constructor](https://cactuscompute.com/docs/react-native#constructor-1)
[Methods](https://cactuscompute.com/docs/react-native#methods-2)
[useCactusSTT Hook](https://cactuscompute.com/docs/react-native#usecactusstt-hook)
[State](https://cactuscompute.com/docs/react-native#state-1)
[Methods](https://cactuscompute.com/docs/react-native#methods-3)
[CactusIndex Class](https://cactuscompute.com/docs/react-native#cactusindex-class)
[Constructor](https://cactuscompute.com/docs/react-native#constructor-2)
[Methods](https://cactuscompute.com/docs/react-native#methods-4)
[useCactusIndex Hook](https://cactuscompute.com/docs/react-native#usecactusindex-hook)
[State](https://cactuscompute.com/docs/react-native#state-2)
[Methods](https://cactuscompute.com/docs/react-native#methods-5)
[Type Definitions](https://cactuscompute.com/docs/react-native#type-definitions)
[CactusLMParams](https://cactuscompute.com/docs/react-native#cactuslmparams)
[CactusLMDownloadParams](https://cactuscompute.com/docs/react-native#cactuslmdownloadparams)
[Message](https://cactuscompute.com/docs/react-native#message)
[CompleteOptions](https://cactuscompute.com/docs/react-native#completeoptions)
[Tool](https://cactuscompute.com/docs/react-native#tool)
[CactusLMCompleteParams](https://cactuscompute.com/docs/react-native#cactuslmcompleteparams)
[CactusLMCompleteResult](https://cactuscompute.com/docs/react-native#cactuslmcompleteresult)
[CactusLMTokenizeParams](https://cactuscompute.com/docs/react-native#cactuslmtokenizeparams)
[CactusLMTokenizeResult](https://cactuscompute.com/docs/react-native#cactuslmtokenizeresult)
[CactusLMScoreWindowParams](https://cactuscompute.com/docs/react-native#cactuslmscorewindowparams)
[CactusLMScoreWindowResult](https://cactuscompute.com/docs/react-native#cactuslmscorewindowresult)
[CactusLMEmbedParams](https://cactuscompute.com/docs/react-native#cactuslmembedparams)
[CactusLMEmbedResult](https://cactuscompute.com/docs/react-native#cactuslmembedresult)
[CactusLMImageEmbedParams](https://cactuscompute.com/docs/react-native#cactuslmimageembedparams)
[CactusLMImageEmbedResult](https://cactuscompute.com/docs/react-native#cactuslmimageembedresult)
[CactusModel](https://cactuscompute.com/docs/react-native#cactusmodel)
[ModelOptions](https://cactuscompute.com/docs/react-native#modeloptions)
[CactusSTTParams](https://cactuscompute.com/docs/react-native#cactussttparams)
[CactusSTTDownloadParams](https://cactuscompute.com/docs/react-native#cactussttdownloadparams)
[TranscribeOptions](https://cactuscompute.com/docs/react-native#transcribeoptions)
[CactusSTTTranscribeParams](https://cactuscompute.com/docs/react-native#cactusstttranscribeparams)
[CactusSTTTranscribeResult](https://cactuscompute.com/docs/react-native#cactusstttranscriberesult)
[CactusSTTAudioEmbedParams](https://cactuscompute.com/docs/react-native#cactussttaudioembedparams)
[CactusSTTAudioEmbedResult](https://cactuscompute.com/docs/react-native#cactussttaudioembedresult)
[CactusSTTStreamTranscribeInsertParams](https://cactuscompute.com/docs/react-native#cactussttstreamtranscribeinsertparams)
[StreamTranscribeProcessOptions](https://cactuscompute.com/docs/react-native#streamtranscribeprocessoptions)
[CactusSTTStreamTranscribeProcessParams](https://cactuscompute.com/docs/react-native#cactussttstreamtranscribeprocessparams)
[CactusSTTStreamTranscribeProcessResult](https://cactuscompute.com/docs/react-native#cactussttstreamtranscribeprocessresult)
[CactusSTTStreamTranscribeFinalizeResult](https://cactuscompute.com/docs/react-native#cactussttstreamtranscribefinalizeresult)
[CactusIndexParams](https://cactuscompute.com/docs/react-native#cactusindexparams)
[CactusIndexAddParams](https://cactuscompute.com/docs/react-native#cactusindexaddparams)
[CactusIndexGetParams](https://cactuscompute.com/docs/react-native#cactusindexgetparams)
[CactusIndexGetResult](https://cactuscompute.com/docs/react-native#cactusindexgetresult)
[IndexQueryOptions](https://cactuscompute.com/docs/react-native#indexqueryoptions)
[CactusIndexQueryParams](https://cactuscompute.com/docs/react-native#cactusindexqueryparams)
[CactusIndexQueryResult](https://cactuscompute.com/docs/react-native#cactusindexqueryresult)
[CactusIndexDeleteParams](https://cactuscompute.com/docs/react-native#cactusindexdeleteparams)
[Configuration](https://cactuscompute.com/docs/react-native#configuration)
[Telemetry](https://cactuscompute.com/docs/react-native#telemetry)
[Hybrid Mode](https://cactuscompute.com/docs/react-native#hybrid-mode)
[Cactus Pro](https://cactuscompute.com/docs/react-native#cactus-pro)
[Performance Tips](https://cactuscompute.com/docs/react-native#performance-tips)
[Example App](https://cactuscompute.com/docs/react-native#example-app)
[Next Steps](https://cactuscompute.com/docs/react-native#next-steps)

---