### Run Example App (Desktop)

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Navigate to the example directory and run this Gradle command to launch the example application on your desktop. This demonstrates various CactusSTT features.

```bash
cd example

# For desktop
./gradlew :composeApp:run
```

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

### Example App

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Information about the example application demonstrating CactusSTT features.

```APIDOC
## Example App

Check out the example app in the `example/` directory for a complete Kotlin Multiplatform implementation showing:
- Model discovery and fetching available models
- Model downloading with progress tracking
- Text completion with both regular and streaming modes
- Speech-to-text transcription with Whisper
- Voice model management
- Embedding generation
- Function calling capabilities
- Error handling and status management
- Compose Multiplatform UI integration

To run the example:
```bash
cd example

# For desktop
./gradlew :composeApp:run

# For Android/iOS - use Android Studio or Xcode
```
```

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

### Install Debug Build on Android

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/example/README.md

Run this command to install the debug version of the application on an Android device or emulator.

```bash
./gradlew composeApp:installDebug
```

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

### Example Usage of Tool Filtering

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Demonstrates how to initialize CactusLM with tool filtering enabled and use it with a list of tools for a user query. The output shows the reduction in the number of tools passed to the model.

```kotlin
import com.cactus.CactusLM
import com.cactus.services.ToolFilterConfig
import com.cactus.services.ToolFilterStrategy
import com.cactus.models.CactusTool
import kotlinx.coroutines.runBlocking
import com.cactus.models.ChatMessage
import com.cactus.models.CactusCompletionParams
import com.cactus.models.CactusInitParams

runBlocking {
    val lm = CactusLM(
        enableToolFiltering = true,
        toolFilterConfig = ToolFilterConfig.simple(maxTools = 3)
    )
    
    lm.initializeModel(CactusInitParams(model = "qwen3-0.6"))
    
    // Define many tools
    val tools = listOf(
        CactusTool(/* weather tool */),
        CactusTool(/* calculator tool */),
        CactusTool(/* search tool */),
        CactusTool(/* email tool */),
        CactusTool(/* calendar tool */),
        // ... more tools
    )
    
    // Tool filtering automatically selects the most relevant tools
    val result = lm.generateCompletion(
        messages = listOf(
            ChatMessage(content = "What's the weather like today?", role = "user")
        ),
        params = CactusCompletionParams(
            tools = tools,  // All tools provided
            temperature = 0.7f
        )
    )
    
    // Only the most relevant tools (e.g., weather tool) are sent to the model
    // Console output will show: "Tool filtering: 10 -> 3 tools"
}
```

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

### Platform-Specific Setup

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Instructions for setting up CactusSTT on Android and iOS platforms.

```APIDOC
## Platform-Specific Setup

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

### iOS
- Add the Cactus package dependency in Xcode
- Requires iOS 12.0+
- Supports ARM64 and Simulator ARM64
```

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

### Enable Tool Filtering with Default Settings

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Enables tool filtering with the default SIMPLE strategy and a maximum of 3 tools. This is a quick way to start optimizing tool usage.

```kotlin
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)
)
```

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

### Text Completion with Local-First Inference Mode

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

This example demonstrates text completion using the `LOCAL_FIRST` inference mode. It attempts local inference and falls back to the remote API if local inference fails. Ensure you provide your `cactusToken` for remote access.

```kotlin
val result = lm.generateCompletion(
    messages = listOf(ChatMessage(content = "Hello!", role = "user")),
    params = CactusCompletionParams(
        mode = InferenceMode.LOCAL_FIRST,
        cactusToken = "your_api_token"
    )
)
```

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

### Stream Language Model Completions in Kotlin

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Demonstrates how to get a streaming response from a language model. Ensure the model is downloaded and initialized before calling generateCompletion. The onToken lambda is called for each received token.

```kotlin
runBlocking {
    val lm = CactusLM()
    
    // Download model (defaults to "qwen3-0.6" if model parameter is omitted)
    lm.downloadModel()
    lm.initializeModel(CactusInitParams())

    // Get the streaming response
    val result = lm.generateCompletion(
        messages = listOf(ChatMessage(content = "Tell me a story", role = "user")),
        onToken = { token, tokenId ->
            print(token)
        }
    )

    // Final result after streaming is complete
    result?.let {
        if (it.success) {
            println("\nFinal response: ${it.response}")
            println("Tokens per second: ${it.tokensPerSecond}")
        }
    }

    lm.unload()
}
```

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

### Transcribe Audio File with CactusSTT

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Use `CactusSTT` for speech recognition with on-device Whisper models. This example shows how to download, initialize, and transcribe an audio file. Includes basic error handling.

```kotlin
import com.cactus.CactusSTT
import com.cactus.CactusInitParams
import com.cactus.CactusTranscriptionParams
import kotlinx.coroutines.runBlocking

runBlocking {
    val stt = CactusSTT()

    try {
        // Download a Whisper model
        stt.downloadModel("whisper-tiny")

        // Initialize the model
        stt.initializeModel(CactusInitParams(model = "whisper-tiny"))

        // Transcribe from audio file
        val result = stt.transcribe(
            filePath = "/path/to/audio.wav",
            params = CactusTranscriptionParams()
        )

        result?.let { transcription ->
            if (transcription.success) {
                println("Transcribed: ${transcription.text}")
                println("Total time: ${transcription.totalTimeMs}ms")
            }
        }
    } catch (e: Exception) {
        println("Transcription failed: ${e.message}")
    }
}
```

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

### Manage Downloaded Models with CactusModelManager in Kotlin

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Provides examples of using the CactusModelManager for basic model management tasks like listing, checking, and deleting downloaded models. This manager operates independently of CactusLM or CactusSTT instances.

```kotlin
import com.cactus.CactusModelManager

// Get a list of all downloaded model slugs
val downloadedModels = CactusModelManager.getDownloadedModels()
println("Downloaded models: $downloadedModels")
// Output: ["qwen3-0.6", "whisper-tiny"]

// Check if a specific model is downloaded
val isDownloaded = CactusModelManager.isModelDownloaded("qwen3-0.6")
println("qwen3-0.6 is downloaded: $isDownloaded")

// Delete a model to free storage
val deleted = CactusModelManager.deleteModel("old-model-slug")
if (deleted) {
    println("Model deleted successfully")
} else {
    println("Model not found")
}

// Get the models directory path for debugging
val modelsPath = CactusModelManager.getModelsDirectory()
println("Models stored at: $modelsPath")
// Android: /data/data/your.app.package/files/models
// iOS: /var/mobile/Containers/Data/Application/.../Documents/models
```

```kotlin
// List all downloaded models and delete unused ones
val models = CactusModelManager.getDownloadedModels()

models.forEach { modelSlug ->
    println("Found model: $modelSlug")

    // Delete if needed
    if (modelSlug == "old-model") {
        CactusModelManager.deleteModel(modelSlug)
        println("Deleted $modelSlug")
    }
}

// Verify deletion
val updatedModels = CactusModelManager.getDownloadedModels()
println("Remaining models: $updatedModels")
```

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

### Get Available Voice Models and Check Download Status

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Retrieve a list of available Whisper voice models and check if a specific model is already downloaded. This is useful for managing model resources.

```kotlin
val whisperModels = CactusSTT().getVoiceModels()

// Check if a model is downloaded
stt.isModelDownloaded("whisper-tiny")
```

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

### Build Project with Gradle

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/example/README.md

Use this command to set up project dependencies for the Kotlin Multiplatform app.

```bash
./gradlew build
```

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

### Enable NPU Acceleration

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Enable NPU acceleration by providing your Pro key. Contact founders@cactuscompute.com to obtain a Pro key.

```kotlin
import com.cactus.CactusConfig

// Enable NPU acceleration with your Pro key
CactusConfig.setProKey("your-pro-key-here") // contact founders@cactuscompute.com to get your token!
```

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

### Building the Library

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Instructions for building the CactusSTT library from source.

```APIDOC
## Building the Library

To build the library from source:

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

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

### Implement Function Calling with Language Models in Kotlin

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Demonstrates how to enable function calling for a language model. Define tools with names, descriptions, and parameters, then pass them to generateCompletion. The response will include tool calls if the model decides to invoke a function.

```kotlin
import com.cactus.models.CactusTool
import com.cactus.models.CactusFunction
import com.cactus.models.ToolParametersSchema
import com.cactus.models.ToolParameter
import com.cactus.models.createTool

runBlocking {
    val lm = CactusLM()
    
    lm.downloadModel()
    lm.initializeModel(CactusInitParams())

    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(content = "What's the weather in New York?", role = "user")),
        params = CactusCompletionParams(
            tools = tools
        )
    )

    result?.toolCalls?.forEach { toolCall ->
        println("Tool: ${toolCall.name}")
        println("Arguments: ${toolCall.arguments}")
    }

    lm.unload()
}
```

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

### Basic LLM Text Completion

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Demonstrates basic text completion using the `CactusLM` class. This includes downloading, initializing a model, generating a completion, and cleaning up resources. Ensure models are downloaded and initialized before generating completions.

```kotlin
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()
    }
}
```

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

### Discover Available Language Models in Kotlin

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Shows how to retrieve a list of all available language models and their properties. This is useful for understanding model capabilities before downloading or initializing them.

```kotlin
runBlocking {
    val lm = CactusLM()

    // Get list of available models
    val models = lm.getModels()

    models.forEach { model ->
        println("Model: ${model.name}")
        println("  Slug: ${model.slug}")
        println("  Size: ${model.size_mb} MB")
        println("  Tool calling: ${model.supports_tool_calling}")
        println("  Vision: ${model.supports_vision}")
        println("  Downloaded: ${model.isDownloaded}")
    }
}
```

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

### Basic Vision Analysis with CactusLM

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Use this snippet to perform basic image analysis using the CactusLM. Ensure models are downloaded and initialized before calling generateCompletion. The response includes the analysis text and performance metrics.

```kotlin
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 {
        // Get available vision models
        val models = lm.getModels()
        val visionModels = models.filter { it.supports_vision }

        // Download and initialize a vision model
        lm.downloadModel(visionModels.first().slug)
        lm.initializeModel(CactusInitParams(model = visionModels.first().slug))

        // Analyze an image
        val result = lm.generateCompletion(
            messages = listOf(
                ChatMessage("You are a helpful AI assistant that can analyze images.", "system"),
                ChatMessage(
                    content = "Describe this image in detail.",
                    role = "user",
                    images = listOf("/path/to/image.jpg")
                )
            ),
            params = CactusCompletionParams(maxTokens = 300)
        )

        result?.let { response ->
            if (response.success) {
                println("Analysis: ${response.response}")
                println("Tokens per second: ${response.tokensPerSecond}")
                println("Time to first token: ${response.timeToFirstTokenMs}ms")
            }
        }
    } finally {
        lm.unload()
    }
}
```

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

### Configure Simple Tool Filtering in Kotlin

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Enable intelligent tool filtering with the SIMPLE strategy for fast keyword matching. Configure maximum tools and similarity threshold.

```kotlin
import com.cactus.CactusLM
import com.cactus.services.ToolFilterConfig
import com.cactus.services.ToolFilterStrategy
import com.cactus.CactusInitParams
import com.cactus.CactusCompletionParams
import com.cactus.ChatMessage
import kotlinx.coroutines.runBlocking

runBlocking {
    // Enable with SIMPLE strategy (fast keyword matching)
    val lm = CactusLM(
        enableToolFiltering = true,
        toolFilterConfig = ToolFilterConfig(
            strategy = ToolFilterStrategy.SIMPLE,
            maxTools = 3,
            similarityThreshold = 0.3
        )
    )

    // Or use SEMANTIC strategy for more accurate filtering
    val lmSemantic = CactusLM(
        enableToolFiltering = true,
        toolFilterConfig = ToolFilterConfig(
            strategy = ToolFilterStrategy.SEMANTIC,
            maxTools = 3,
            similarityThreshold = 0.5
        )
    )

    lm.initializeModel(CactusInitParams(model = "qwen3-0.6"))

    // When many tools are provided, only the most relevant are sent to the model
    val result = lm.generateCompletion(
        messages = listOf(ChatMessage("What's the weather today?", "user")),
        params = CactusCompletionParams(tools = manyTools)
    )
    // Console output: "Tool filtering: 10 -> 3 tools"
}
```

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

### Define and Use Tools for Function Calling in Kotlin

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Define tools with parameters and enable AI models to generate function calls based on user queries. Ensure necessary imports and model initialization.

```kotlin
import com.cactus.CactusLM
import com.cactus.CactusInitParams
import com.cactus.CactusCompletionParams
import com.cactus.ChatMessage
import com.cactus.models.ToolParameter
import com.cactus.models.createTool
import kotlinx.coroutines.runBlocking

runBlocking {
    val lm = CactusLM()

    lm.downloadModel()
    lm.initializeModel(CactusInitParams())

    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
                ),
                "units" to ToolParameter(
                    type = "string",
                    description = "Temperature units (celsius or fahrenheit)",
                    required = false
                )
            )
        )
    )

    val result = lm.generateCompletion(
        messages = listOf(
            ChatMessage("You are a helpful AI assistant.", "system"),
            ChatMessage("What's the weather in New York?", "user")
        ),
        params = CactusCompletionParams(
            tools = tools,
            maxTokens = 200
        )
    )

    result?.toolCalls?.forEach { toolCall ->
        println("Tool: ${toolCall.name}")
        println("Arguments: ${toolCall.arguments}")
        // Output: Tool: get_weather
        // Output: Arguments: {location=New York}
    }

    lm.unload()
}
```

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

### Enable NPU Acceleration with CactusConfig

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Enables NPU (Neural Processing Unit) acceleration for supported devices. Requires a Pro key obtained from Cactus.

```kotlin
import com.cactus.CactusConfig

// Enable NPU acceleration with Pro key
CactusConfig.setProKey("your-pro-key-here")
```

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

### Add Repository to settings.gradle.kts

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Configure your project to use the Maven Central repository by adding it to your `settings.gradle.kts` file.

```kotlin
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}
```

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

### Run iOS Simulator Tests

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/example/README.md

Execute this command to run tests on an iOS simulator for the application.

```bash
./gradlew composeApp:iosSimulatorArm64Test
```

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

### Build CactusSTT Library

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Execute this bash command to build the CactusSTT library and publish it to your local Maven repository. This is part of the development process.

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

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

### Analyze Image with Vision Model

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Use a vision-capable model to analyze and describe an image. Ensure the model supports vision and is initialized before use. Handles potential errors during the process.

```kotlin
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 {
        // Get vision-capable models
        val models = lm.getModels()
        val visionModel = models.first { it.supports_vision }

        lm.downloadModel(visionModel.slug)
        lm.initializeModel(CactusInitParams(model = visionModel.slug))

        val result = lm.generateCompletion(
            messages = listOf(
                ChatMessage("You are a helpful AI assistant.", "system"),
                ChatMessage(
                    content = "Describe this image in detail.",
                    role = "user",
                    images = listOf("/path/to/image.jpg")
                )
            ),
            params = CactusCompletionParams(maxTokens = 300)
        )

        result?.let { response ->
            if (response.success) {
                println("Analysis: ${response.response}")
            }
        }
    } finally {
        lm.unload()
    }
}
```

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

### Transcribe Audio with Local-First Fallback

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Use this snippet to transcribe audio from a file, with a fallback to a remote API if local transcription fails. Ensure you provide the correct file path and API key.

```kotlin
// Transcribe from audio file with remote fallback
val fileResult = stt.transcribe(
    filePath = "/path/to/audio.wav",
    params = CactusTranscriptionParams(),
    mode = TranscriptionMode.LOCAL_FIRST,
    apiKey = "your_wispr_api_key"
)
```

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

### Streaming Text Generation with CactusLM

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Generate text completions with real-time token streaming using the `onToken` callback. This allows for progressive display of responses as they are generated. Remember to call `unload()` after use.

```kotlin
import com.cactus.CactusLM
import com.cactus.CactusInitParams
import com.cactus.ChatMessage
import kotlinx.coroutines.runBlocking

runBlocking {
    val lm = CactusLM()

    lm.downloadModel()
    lm.initializeModel(CactusInitParams())

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

    result?.let {
        if (it.success) {
            println("\nFinal response: ${it.response}")
            println("Tokens per second: ${it.tokensPerSecond}")
        }
    }

    lm.unload()
}
```

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

### Custom Tool Filtering Configuration

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Provides a custom configuration for tool filtering, specifying the SIMPLE strategy, a maximum of 5 tools, and a similarity threshold of 0.3. Adjust these parameters for fine-grained control.

```kotlin
import com.cactus.CactusLM
import com.cactus.services.ToolFilterConfig
import com.cactus.services.ToolFilterStrategy

// Custom configuration with SIMPLE strategy
val lm = CactusLM(
    enableToolFiltering = true,
    toolFilterConfig = ToolFilterConfig(
        strategy = ToolFilterStrategy.SIMPLE,
        maxTools = 5,
        similarityThreshold = 0.3
    )
)
```

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

### Text Completion with Inference Modes

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Explains how to generate text completions using `CactusLM` and details the different inference modes available, including local, remote, and fallback strategies.

```APIDOC
## Text Completion with Inference Modes

### Description
Generates text completions based on a list of chat messages. This function supports various inference modes to balance between on-device and cloud-based processing, and allows for streaming responses.

### Method
`suspend fun generateCompletion(messages: List<ChatMessage>, params: CactusCompletionParams = CactusCompletionParams(), onToken: CactusStreamingCallback? = null): CactusCompletionResult?`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **messages** (List<ChatMessage>) - Required - A list of chat messages representing the conversation history.
- **params** (CactusCompletionParams) - Optional - Parameters for text completion, including inference mode, token, and generation settings. Defaults to `CactusCompletionParams()`.
- **onToken** (CactusStreamingCallback?) - Optional - A callback function to receive tokens as they are generated (for streaming).

### Inference Modes
Controlled by the `mode` parameter in `CactusCompletionParams`:
- `InferenceMode.LOCAL`: (Default) Performs inference locally on the device.
- `InferenceMode.REMOTE`: Performs inference using a remote API. Requires `cactusToken`.
- `InferenceMode.LOCAL_FIRST`: Attempts local inference first. If it fails, it falls back to the remote API.
- `InferenceMode.REMOTE_FIRST`: Attempts remote inference first. If it fails, it falls back to the local model.

### Request Example (Local-First Fallback)
```kotlin
val result = lm.generateCompletion(
    messages = listOf(ChatMessage(content = "Hello!", role = "user")),
    params = CactusCompletionParams(
        mode = InferenceMode.LOCAL_FIRST,
        cactusToken = "your_api_token"
    )
)
```

### Response
#### Success Response (200)
- **success** (Boolean) - Indicates if the completion generation was successful.
- **response** (String?) - The generated text completion.
- **timeToFirstTokenMs** (Double?) - Time taken to generate the first token.
- **totalTimeMs** (Double?) - Total time taken for the completion.
- **tokensPerSecond** (Double?) - Tokens generated per second.
- **prefillTokens** (Int?) - Number of tokens in the prefill phase.
- **decodeTokens** (Int?) - Number of tokens decoded.
- **totalTokens** (Int?) - Total number of tokens generated.
- **toolCalls** (List<ToolCall>?) - A list of tool calls made by the model.

#### Response Example
```json
{
  "success": true,
  "response": "Hello there! How can I help you today?",
  "timeToFirstTokenMs": 150.5,
  "totalTimeMs": 1200.0,
  "tokensPerSecond": 25.5,
  "prefillTokens": 10,
  "decodeTokens": 50,
  "totalTokens": 60,
  "toolCalls": []
}
```
```

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

### Stream Transcription with Real-time Tokens

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Transcribe speech with real-time token streaming for progressive display. The `onToken` callback prints each recognized word as it becomes available.

```kotlin
import com.cactus.CactusSTT
import com.cactus.CactusInitParams
import com.cactus.CactusTranscriptionParams
import kotlinx.coroutines.runBlocking

runBlocking {
    val stt = CactusSTT()

    stt.downloadModel("whisper-tiny")
    stt.initializeModel(CactusInitParams(model = "whisper-tiny"))

    val result = stt.transcribe(
        filePath = "/path/to/audio.wav",
        params = CactusTranscriptionParams(),
        onToken = { token, _ ->
            print(token) // Print each word as it's recognized
        }
    )

    result?.let { transcription ->
        if (transcription.success) {
            println("\nFinal transcription: ${transcription.text}")
        }
    }
}
```

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

### Streaming Vision Analysis with CactusLM

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

This snippet demonstrates how to perform image analysis with streaming responses using CactusLM. The `onToken` callback receives partial results as they are generated, allowing for real-time display.

```kotlin
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()
}
```

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

### Helper Functions

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Details utility functions available in the SDK, such as creating tools.

```APIDOC
## Helper Functions

### Description
Utility functions to assist in creating and managing SDK components.

### Functions

- **`createTool(name: String, description: String, parameters: Map<String, ToolParameter>): CactusTool`**
  - **Description**: Helper function to create a `CactusTool` with the correct schema.
  - **Parameters**:
    - `name` (String) - Required - The name of the tool.
    - `description` (String) - Required - A description of the tool's purpose.
    - `parameters` (Map<String, ToolParameter>) - Required - A map defining the tool's parameters.
  - **Returns**: A `CactusTool` object.

### Example Usage
```kotlin
val searchParams = mapOf(
    "query" to ToolParameter(type = "string", description = "The search query")
)
val searchTool = createTool(
    name = "search",
    description = "Search the web for information",
    parameters = searchParams
)
```
```

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

### Discover Available Models with CactusLM and CactusSTT

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Fetches available language and voice models from the Cactus model registry. Results are cached locally. Requires instances of `CactusLM` and `CactusSTT`.

```kotlin
import com.cactus.CactusLM
import com.cactus.CactusSTT
import kotlinx.coroutines.runBlocking

runBlocking {
    val lm = CactusLM()

    // Get list of available LLM models
    val models = lm.getModels()

    models.forEach {
        println("Model: ${it.name}")
        println("  Slug: ${it.slug}")
        println("  Size: ${it.size_mb} MB")
        println("  Tool calling: ${it.supports_tool_calling}")
        println("  Vision: ${it.supports_vision}")
        println("  Downloaded: ${it.isDownloaded}")
    }

    // Get available Whisper/voice models
    val stt = CactusSTT()
    val voiceModels = stt.getVoiceModels()

    voiceModels.forEach {
        println("Voice Model: ${it.slug} (${it.size_mb} MB)")
    }
}
```

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

### Define Cactus Initialization Parameters

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Use this data class to specify initialization parameters for Cactus, such as the model slug and context window size.

```kotlin
data class CactusInitParams(
    val model: String? = null,          // Model slug (e.g., "qwen3-0.6")
    val contextSize: Int? = null        // Context window size (default: 2048)
)
```

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

### Manage Downloaded Models with CactusModelManager

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Provides utilities to manage downloaded models without requiring `CactusLM` or `CactusSTT` instances. Useful for storage management and model inspection. Accesses models via a singleton instance.

```kotlin
import com.cactus.CactusModelManager

// Get list of all downloaded model slugs
val downloadedModels = CactusModelManager.getDownloadedModels()
println("Downloaded models: $downloadedModels")
// Output: ["qwen3-0.6", "whisper-tiny"]

// Check if a specific model is downloaded
val isDownloaded = CactusModelManager.isModelDownloaded("qwen3-0.6")
println("qwen3-0.6 is downloaded: $isDownloaded")

// Delete a model to free storage
val deleted = CactusModelManager.deleteModel("old-model-slug")
if (deleted) {
    println("Model deleted successfully")
} else {
    println("Model not found")
}

// Get the models directory path
val modelsPath = CactusModelManager.getModelsDirectory()
println("Models stored at: $modelsPath")
// Android: /data/data/your.app.package/files/models
// iOS: /var/mobile/Containers/Data/Application/.../Documents/models
```

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

### Define Cactus Completion Parameters

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Configure text generation parameters like temperature, top-K, top-P, and maximum tokens. Supports tool definitions and custom stop sequences.

```kotlin
data class CactusCompletionParams(
    val model: String? = null,
    val temperature: Double? = null,
    val topK: Int? = null,
    val topP: Double? = null,
    val maxTokens: Int = 512,
    val stopSequences: List<String> = listOf("<|im_end|>", "<end_of_turn>"),
    val tools: List<CactusTool> = emptyList(),
    val mode: InferenceMode = InferenceMode.LOCAL,
    val cactusToken: String? = null,
    val forceTools: Boolean? = null     // Force model to call a tool
)
```

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

### Embedding Generation

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Demonstrates how to generate embeddings for a given text using the CactusLM class. It includes downloading and initializing the model, generating the embedding, and printing the results.

```APIDOC
## Embedding Generation

### Description
Generates embeddings for the provided text using the `CactusLM` class. This process involves downloading and initializing the model before generating the embeddings and then unloading the model.

### Method
`suspend fun generateEmbedding(text: String, modelName: String? = null): CactusEmbeddingResult?`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **text** (String) - Required - The input text for which to generate embeddings.
- **modelName** (String?) - Optional - The name of the model to use for embedding generation. Defaults to the currently initialized model.

### Request Example
```kotlin
runBlocking {
    val lm = CactusLM()
    lm.downloadModel()
    lm.initializeModel(CactusInitParams())
    val result = lm.generateEmbedding(text = "The quick brown fox jumps over the lazy dog")
    result?.let {
        if (it.success) {
            println("Embedding dimension: ${it.dimension}")
            println("First 5 values: ${it.embeddings.take(5)}")
        }
    }
    lm.unload()
}
```

### Response
#### Success Response (200)
- **success** (Boolean) - Indicates if the embedding generation was successful.
- **embeddings** (List<Double>) - A list of double values representing the embedding vector.
- **dimension** (Int?) - The dimension of the embedding vector.

#### Response Example
```json
{
  "success": true,
  "embeddings": [0.1, 0.2, 0.3, 0.4, 0.5, ...],
  "dimension": 768
}
```
```

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

### Streaming Speech-to-Text Transcription with CactusSTT

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

This snippet demonstrates streaming speech-to-text transcription using CactusSTT. The `onToken` callback provides incremental transcription results as they become available, suitable for real-time applications.

```kotlin
import com.cactus.CactusSTT
import com.cactus.CactusInitParams
import com.cactus.CactusTranscriptionParams
import kotlinx.coroutines.runBlocking

runBlocking {
    val stt = CactusSTT()

    try {
        // Download and initialize model
        stt.downloadModel("whisper-tiny")
        stt.initializeModel(CactusInitParams(model = "whisper-tiny"))

        // Transcribe with token streaming
        val result = stt.transcribe(
            filePath = "/path/to/audio.wav",
            params = CactusTranscriptionParams(),
            onToken = { token, _ ->
                print(token)
            }
        )

        result?.let { transcription ->
            if (transcription.success) {
                println("\nFinal transcription: ${transcription.text}")
            }
        }
    } catch (e: Exception) {
        println("Transcription failed: ${e.message}")
    }
}
```

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

### CactusLM Class API Reference

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Provides a detailed reference for the `CactusLM` class, outlining its methods for model management and inference.

```APIDOC
## CactusLM Class API Reference

### Description
Reference for the `CactusLM` class methods, covering model lifecycle management and core inference functionalities.

### Methods

- **`suspend fun downloadModel(model: String = "qwen3-0.6")`**
  - **Description**: Downloads an LLM model by its slug. Throws an exception on failure.
  - **Parameters**:
    - `model` (String) - Optional - The slug of the model to download (e.g., "qwen3-0.6", "gemma3-270m"). Defaults to "qwen3-0.6".

- **`suspend fun initializeModel(params: CactusInitParams)`**
  - **Description**: Initializes a model for inference. Throws an exception on failure.
  - **Parameters**:
    - `params` (CactusInitParams) - Required - Parameters for model initialization.

- **`suspend fun generateCompletion(messages: List<ChatMessage>, params: CactusCompletionParams = CactusCompletionParams(), onToken: CactusStreamingCallback? = null): CactusCompletionResult?`**
  - **Description**: Generates text completion. Supports streaming via the `onToken` callback and different inference modes.
  - **Parameters**:
    - `messages` (List<ChatMessage>) - Required - The list of messages for the conversation.
    - `params` (CactusCompletionParams) - Optional - Parameters for text completion.
    - `onToken` (CactusStreamingCallback?) - Optional - Callback for streaming tokens.

- **`suspend fun generateEmbedding(text: String, modelName: String? = null): CactusEmbeddingResult?`**
  - **Description**: Generates embeddings for the given text.
  - **Parameters**:
    - `text` (String) - Required - The input text.
    - `modelName` (String?) - Optional - The name of the model to use.

- **`suspend fun getModels(): List<CactusModel>`**
  - **Description**: Retrieves a list of available models. Results are cached locally.
  - **Parameters**: None.

- **`fun reset()`**
  - **Description**: Resets the model context, clearing conversation history and state without unloading the model.
  - **Parameters**: None.

- **`fun unload()`**
  - **Description**: Unloads the current model and frees resources.
  - **Parameters**: None.

- **`fun isLoaded(): Boolean`**
  - **Description**: Checks if a model is currently loaded.
  - **Parameters**: None.

### Example Usage (Initialization and Completion)
```kotlin
runBlocking {
    val lm = CactusLM()
    lm.downloadModel("gemma3-270m")
    lm.initializeModel(CactusInitParams(model = "gemma3-270m"))
    val result = lm.generateCompletion(
        messages = listOf(ChatMessage(content = "Explain quantum computing", role = "user"))
    )
    println(result?.response)
    lm.unload()
}
```
```

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

### Basic Speech-to-Text Transcription with CactusSTT

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Use this code to perform basic speech-to-text transcription from an audio file using the CactusSTT class. It requires downloading and initializing a Whisper model before transcription. Error handling is included for download, initialization, and transcription failures.

```kotlin
import com.cactus.CactusSTT
import com.cactus.CactusInitParams
import com.cactus.CactusTranscriptionParams
import kotlinx.coroutines.runBlocking

runBlocking {
    val stt = CactusSTT()

    try {
        // Download a Whisper model (e.g., whisper-tiny)
        // Throws exception on failure
        stt.downloadModel("whisper-tiny")

        // Initialize the model
        // Throws exception on failure
        stt.initializeModel(CactusInitParams(model = "whisper-tiny"))

        // Transcribe from an audio file
        val result = stt.transcribe(
            filePath = "/path/to/audio.wav",
            params = CactusTranscriptionParams()
        )

        result?.let { transcription ->
            if (transcription.success) {
                println("Transcribed: ${transcription.text}")
                println("Total time: ${transcription.totalTimeMs}ms")
            }
        }
    } catch (e: Exception) {
        println("Transcription failed: ${e.message}")
    }
}
```

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

### Add Dependency to build.gradle.kts

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Include the Cactus library as a dependency in your KMP project's `build.gradle.kts` file for common main sources.

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

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

### Text Generation with CactusLM

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Use the `CactusLM` class for text completion with local inference. It handles model downloading, initialization, and generation. Ensure to call `unload()` in a `finally` block.

```kotlin
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 (defaults to "qwen3-0.6" if not specified)
        lm.downloadModel("qwen3-0.6")

        // Initialize the model with optional context size
        lm.initializeModel(
            CactusInitParams(
                model = "qwen3-0.6",
                contextSize = 2048
            )
        )

        // Generate completion
        val result = lm.generateCompletion(
            messages = listOf(
                ChatMessage(content = "Hello, how are you?", role = "user")
            )
        )

        result?.let {
            if (it.success) {
                println("Response: ${it.response}")
                println("Tokens per second: ${it.tokensPerSecond}")
                println("Time to first token: ${it.timeToFirstTokenMs}ms")
            }
        }
    } finally {
        lm.unload()
    }
}
```

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

### Initialize Cactus Context in MainActivity

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Ensure the Cactus context is initialized in your Activity's `onCreate()` method before utilizing any SDK features. This is a mandatory step.

```kotlin
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
    }
}
```

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

### Initialize Cactus Context in Android Activity

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Initialize the Cactus context in your Android Activity's `onCreate()` method. This is required for proper native library loading before using any SDK functionality.

```kotlin
import com.cactus.CactusContextInitializer
import android.os.Bundle
import androidx.activity.ComponentActivity

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Initialize Cactus context (required)
        CactusContextInitializer.initialize(this)

        // Your app code here
    }
}
```

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

### Add Cactus Dependency to Kotlin Multiplatform Project

Source: https://context7.com/cactus-compute/cactus-kotlin/llms.txt

Configure the repository and add the Cactus implementation dependency in your `settings.gradle.kts` and `build.gradle.kts` files.

```kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

// build.gradle.kts
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("com.cactuscompute:cactus:1.4.1-beta")
            }
        }
    }
}
```

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

### CactusSTT Class API Reference

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Detailed reference for the CactusSTT class, including its constructor, methods, and associated data classes.

```APIDOC
## 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? = null, prompt: String = "<|startoftranscript|><|en|><|transcribe|><|notimestamps|>". "", params: CactusTranscriptionParams = CactusTranscriptionParams(), onToken: CactusStreamingCallback? = null, mode: TranscriptionMode = TranscriptionMode.LOCAL, apiKey: String? = null, audioBuffer: ByteArray? = null): CactusTranscriptionResult?` - Transcribe speech from an audio file or audio buffer. Use `filePath` for file-based transcription or `audioBuffer` for stream-based transcription (e.g., from microphone). Audio buffer must be 16-bit PCM, 16kHz, mono, minimum 32,000 bytes. 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 reset()` - Reset the model context, clearing accumulated state without unloading the model. Useful for starting fresh transcriptions.
- `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

- `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`).
```

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

### SEMANTIC Strategy for Accurate Filtering

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Configures tool filtering to use the SEMANTIC strategy for more accurate matching, with a maximum of 3 tools and a similarity threshold of 0.5. This is suitable for complex queries where precision is key.

```kotlin
import com.cactus.CactusLM
import com.cactus.services.ToolFilterConfig
import com.cactus.services.ToolFilterStrategy

// Use SEMANTIC strategy for more accurate filtering
val lm = CactusLM(
    enableToolFiltering = true,
    toolFilterConfig = ToolFilterConfig(
        strategy = ToolFilterStrategy.SEMANTIC,
        maxTools = 3,
        similarityThreshold = 0.5
    )
)
```

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

### Android Manifest Permissions

Source: https://github.com/cactus-compute/cactus-kotlin/blob/main/README.md

Declare necessary permissions in your Android manifest for internet access (model downloads) and audio recording (transcription).

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