cactus-react-native 1.0.1 → 1.0.2

package/README.md

@@ -10,10 +10,78 @@
 npm install cactus-react-native react-native-nitro-modules
 ```
 
+## Quick Start
+
+Get started with Cactus in just a few lines of code:
+
+```typescript
+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:**
+
+```tsx
+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
 
 ### Completion
 
+Generate text responses from the model by providing a conversation history.
+
 #### Class
 
 ```typescript
@@ -22,9 +90,7 @@ import { CactusLM, type Message } from 'cactus-react-native';
 const cactusLM = new CactusLM();
 
 const messages: Message[] = [{ role: 'user', content: 'Hello, World!' }];
-const onToken = (token: string) => {
-  console.log('Received token:', token);
-};
+const onToken = (token: string) => { console.log('Token:', token) };
 
 const result = await cactusLM.complete({ messages, onToken });
 console.log('Completion result:', result);
@@ -54,8 +120,64 @@ const App = () => {
 };
 ```
 
+### Vision
+
+Vision allows you to pass images along with text prompts, enabling the model to analyze and understand visual content.
+
+#### Class
+
+```typescript
+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
+
+```tsx
+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
 
+Enable the model to generate function calls by defining available tools and their parameters.
+
 #### Class
 
 ```typescript
@@ -87,11 +209,12 @@ const messages: Message[] = [
 
 const result = await cactusLM.complete({ messages, tools });
 console.log('Response:', result.response);
+console.log('Function calls:', result.functionCalls);
 ```
 
 #### Hook
 
-```typescript
+```tsx
 import { useCactusLM, type Message, type Tool } from 'cactus-react-native';
 
 const tools: Tool[] = [
@@ -129,8 +252,58 @@ const App = () => {
 };
 ```
 
+### 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
+
+```typescript
+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
+
+```tsx
+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>
+    </>
+  );
+};
+```
+
 ### Embedding
 
+Convert text into numerical vector representations that capture semantic meaning, useful for similarity search and semantic understanding.
+
 #### Class
 
 ```typescript
@@ -145,7 +318,7 @@ console.log('Embedding vector length:', result.embedding.length);
 
 #### Hook
 
-```typescript
+```tsx
 import { useCactusLM } from 'cactus-react-native';
 
 const App = () => {
@@ -163,32 +336,37 @@ const App = () => {
 
 ## API Reference
 
-### `CactusLM` Class
+### CactusLM Class
 
 #### Constructor
 
 **`new CactusLM(params?: CactusLMParams)`**
 
-- `model` - Model slug (default: `'qwen3-0.6'`)
-- `contextSize` - Context window size (default: `2048`)
+**Parameters:**
+- `model` - Model slug (default: `'qwen3-0.6'`).
+- `contextSize` - Context window size (default: `2048`).
+- `corpusDir` - Directory containing text files for RAG (default: `undefined`).
 
 #### Methods
 
 **`download(params?: CactusLMDownloadParams): Promise<void>`**
 
-- Downloads the model.
+Downloads the model. If the model is already downloaded, returns immediately with progress at 100%. Throws an error if a download is already in progress. Automatically refreshes the models list after successful download.
+
+**Parameters:**
 - `onProgress` - Callback for download progress (0-1).
 
 **`init(): Promise<void>`**
 
-- Initializes the model and prepares it for inference.
+Initializes the model and prepares it for inference. Safe to call multiple times (idempotent). Throws an error if the model is not downloaded yet. Automatically initializes telemetry if not already done.
 
 **`complete(params: CactusLMCompleteParams): Promise<CactusLMCompleteResult>`**
 
-- Performs text completion with optional streaming and tool support (initializes the model if needed).
+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).
@@ -199,61 +377,68 @@ const App = () => {
 
 **`embed(params: CactusLMEmbedParams): Promise<CactusLMEmbedResult>`**
 
-- Generates embeddings for the given text (initializes the model if needed).
+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.
 
 **`stop(): Promise<void>`**
 
-- Stops ongoing generation.
+Stops ongoing generation.
 
 **`reset(): Promise<void>`**
 
-- Resets the model's internal state, clearing any cached context.
+Resets the model's internal state, clearing any cached context. Automatically calls `stop()` first.
 
 **`destroy(): Promise<void>`**
 
-- Releases all resources associated with the model.
+Releases all resources associated with the model. Automatically calls `stop()` first. Safe to call even if the model is not initialized.
 
 **`getModels(params?: CactusLMGetModelsParams): Promise<CactusModel[]>`**
 
-- Fetches available models and persists the results locally.
-- `forceRefresh` - If `true`, forces a fetch from the server and updates the local data (default: `false`).
+Fetches available models and persists the results locally for caching. Returns cached results if available, unless `forceRefresh` is `true`. Checks the download status for each model and includes it in the results.
 
-### `useCactusLM` Hook
+**Parameters:**
+- `forceRefresh` - If `true`, fetches from the server and updates the local cache (default: `false`).
+
+### useCactusLM Hook
+
+The `useCactusLM` hook manages a `CactusLM` instance with reactive state. When model parameters (`model`, `contextSize`, or `corpusDir`) change, the hook creates a new instance and resets all state. The hook automatically cleans up resources when the component unmounts.
 
 #### State
 
-- `completion: string` - Current generated text.
-- `isGenerating: boolean` - Whether the model is currently generating.
+- `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.
+- `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). `0` if not downloading.
-- `error: string | null` - Last error message, or `null` if there is no error.
+- `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
 
-- `download(params?: CactusLMDownloadParams): Promise<void>`
-- `init(): Promise<void>`
-- `complete(params: CactusLMCompleteParams): Promise<CactusLMCompleteResult>`
-- `embed(params: CactusLMEmbedParams): Promise<CactusLMEmbedResult>`
-- `stop(): Promise<void>`
-- `reset(): Promise<void>`
-- `destroy(): Promise<void>`
-- `getModels(params?: CactusLMGetModelsParams): Promise<CactusModel[]>`
+- `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.
+- `embed(params: CactusLMEmbedParams): Promise<CactusLMEmbedResult>` - Generates embeddings for the given text. Sets `isGenerating` to `true` during operation.
+- `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(params?: CactusLMGetModelsParams): Promise<CactusModel[]>` - Fetches available models and returns them. Results are cached locally.
 
 ## Type Definitions
 
-### `CactusLMParams`
+### CactusLMParams
 
 ```typescript
 interface CactusLMParams {
   model?: string;
   contextSize?: number;
+  corpusDir?: string;
 }
 ```
 
-### `CactusLMDownloadParams`
+### CactusLMDownloadParams
 
 ```typescript
 interface CactusLMDownloadParams {
@@ -261,16 +446,17 @@ interface CactusLMDownloadParams {
 }
 ```
 
-### `Message`
+### Message
 
 ```typescript
 interface Message {
   role: 'user' | 'assistant' | 'system';
-  content: string;
+  content?: string;
+  images?: string[];
 }
 ```
 
-### `Options`
+### Options
 
 ```typescript
 interface Options {
@@ -282,7 +468,7 @@ interface Options {
 }
 ```
 
-### `Tool`
+### Tool
 
 ```typescript
 interface Tool {
@@ -302,7 +488,7 @@ interface Tool {
 }
 ```
 
-### `CactusLMCompleteParams`
+### CactusLMCompleteParams
 
 ```typescript
 interface CactusLMCompleteParams {
@@ -313,7 +499,7 @@ interface CactusLMCompleteParams {
 }
 ```
 
-### `CactusLMCompleteResult`
+### CactusLMCompleteResult
 
 ```typescript
 interface CactusLMCompleteResult {
@@ -332,7 +518,7 @@ interface CactusLMCompleteResult {
 }
 ```
 
-### `CactusLMEmbedParams`
+### CactusLMEmbedParams
 
 ```typescript
 interface CactusLMEmbedParams {
@@ -340,7 +526,7 @@ interface CactusLMEmbedParams {
 }
 ```
 
-### `CactusLMEmbedResult`
+### CactusLMEmbedResult
 
 ```typescript
 interface CactusLMEmbedResult {
@@ -348,7 +534,7 @@ interface CactusLMEmbedResult {
 }
 ```
 
-### `CactusLMGetModelsParams`
+### CactusLMGetModelsParams
 
 ```typescript
 interface CactusLMGetModelsParams {
@@ -356,7 +542,7 @@ interface CactusLMGetModelsParams {
 }
 ```
 
-### `CactusModel`
+### CactusModel
 
 ```typescript
 interface CactusModel {
@@ -386,4 +572,14 @@ CactusConfig.telemetryToken = 'your-token-here';
 
 // Disable telemetry
 CactusConfig.isTelemetryEnabled = false;
-```
+```
+
+## 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
+
+Check out [our example app](/example) for a complete React Native implementation.

package/cpp/HybridCactus.cpp

@@ -1,30 +1,41 @@
 #include "HybridCactus.hpp"
 
-namespace margelo::nitro::cactus
-{
+namespace margelo::nitro::cactus {
 HybridCactus::HybridCactus() : HybridObject(TAG) {}
 
-std::shared_ptr<Promise<void>> HybridCactus::init(const std::string &modelPath, double contextSize) {
-  return Promise<void>::async([this, modelPath, contextSize]() -> void {
-    std::lock_guard<std::mutex> lock(this->_modelMutex);
+std::shared_ptr<Promise<void>>
+HybridCactus::init(const std::string &modelPath, double contextSize,
+                   const std::optional<std::string> &corpusDir) {
+  return Promise<void>::async(
+      [this, modelPath, contextSize, corpusDir]() -> void {
+        std::lock_guard<std::mutex> lock(this->_modelMutex);
 
-    if (this->_model) {
-      throw std::runtime_error("Cactus model is already initialized");
-    }
+        if (this->_model) {
+          throw std::runtime_error("Cactus model is already initialized");
+        }
 
-    const cactus_model_t model = cactus_init(modelPath.c_str(), contextSize);
+        const cactus_model_t model =
+            cactus_init(modelPath.c_str(), contextSize,
+                        corpusDir ? corpusDir->c_str() : nullptr);
 
-    if (!model) {
-      throw std::runtime_error("Failed to initialize Cactus model");
-    }
+        if (!model) {
+          throw std::runtime_error("Failed to initialize Cactus model");
+        }
 
-    this->_model = model;
-    this->_contextSize = contextSize;
-  });
+        this->_model = model;
+        this->_contextSize = contextSize;
+      });
 }
 
-std::shared_ptr<Promise<std::string>> HybridCactus::complete(const std::string &messagesJson, double responseBufferSize, const std::optional<std::string> &optionsJson, const std::optional<std::string> &toolsJson, const std::optional<std::function<void(const std::string & /* token */, double /* tokenId */)>> &callback) {
-  return Promise<std::string>::async([this, messagesJson, optionsJson, toolsJson, callback, responseBufferSize]() -> std::string {
+std::shared_ptr<Promise<std::string>> HybridCactus::complete(
+    const std::string &messagesJson, double responseBufferSize,
+    const std::optional<std::string> &optionsJson,
+    const std::optional<std::string> &toolsJson,
+    const std::optional<std::function<void(const std::string & /* token */,
+                                           double /* tokenId */)>> &callback) {
+  return Promise<std::string>::async([this, messagesJson, optionsJson,
+                                      toolsJson, callback,
+                                      responseBufferSize]() -> std::string {
     std::lock_guard<std::mutex> lock(this->_modelMutex);
 
     if (!this->_model) {
@@ -32,28 +43,26 @@ std::shared_ptr<Promise<std::string>> HybridCactus::complete(const std::string &
     }
 
     struct CallbackCtx {
-      const std::function<void(const std::string & /* token */, double /* tokenId */)> *callback;
-    } callbackCtx{ callback.has_value() ? &callback.value() : nullptr };
-
-    auto cactusTokenCallback = [](const char* token, uint32_t tokenId, void* userData) {
-      auto* callbackCtx = static_cast<CallbackCtx*>(userData);
-      if (!callbackCtx || !callbackCtx->callback || !(*callbackCtx->callback)) return;
+      const std::function<void(const std::string & /* token */,
+                               double /* tokenId */)> *callback;
+    } callbackCtx{callback.has_value() ? &callback.value() : nullptr};
+
+    auto cactusTokenCallback = [](const char *token, uint32_t tokenId,
+                                  void *userData) {
+      auto *callbackCtx = static_cast<CallbackCtx *>(userData);
+      if (!callbackCtx || !callbackCtx->callback || !(*callbackCtx->callback))
+        return;
       (*callbackCtx->callback)(token, tokenId);
     };
 
     std::string responseBuffer;
     responseBuffer.resize(responseBufferSize);
 
-    int result = cactus_complete(
-                    this->_model,
-                    messagesJson.c_str(),
-                    responseBuffer.data(),
-                    responseBufferSize,
-                    optionsJson ? optionsJson->c_str() : nullptr,
-                    toolsJson ? toolsJson->c_str() : nullptr,
-                    cactusTokenCallback,
-                    &callbackCtx
-                    );
+    int result = cactus_complete(this->_model, messagesJson.c_str(),
+                                 responseBuffer.data(), responseBufferSize,
+                                 optionsJson ? optionsJson->c_str() : nullptr,
+                                 toolsJson ? toolsJson->c_str() : nullptr,
+                                 cactusTokenCallback, &callbackCtx);
 
     if (result < 0) {
       throw std::runtime_error("Cactus completion failed");
@@ -66,27 +75,32 @@ std::shared_ptr<Promise<std::string>> HybridCactus::complete(const std::string &
   });
 }
 
-std::shared_ptr<Promise<std::vector<double>>> HybridCactus::embed(const std::string &text, double embeddingBufferSize) {
-  return Promise<std::vector<double>>::async([this, text, embeddingBufferSize]() -> std::vector<double> {
-    std::lock_guard<std::mutex> lock(this->_modelMutex);
+std::shared_ptr<Promise<std::vector<double>>>
+HybridCactus::embed(const std::string &text, double embeddingBufferSize) {
+  return Promise<std::vector<double>>::async(
+      [this, text, embeddingBufferSize]() -> std::vector<double> {
+        std::lock_guard<std::mutex> lock(this->_modelMutex);
 
-    if (!this->_model) {
-      throw std::runtime_error("Cactus model is not initialized");
-    }
+        if (!this->_model) {
+          throw std::runtime_error("Cactus model is not initialized");
+        }
 
-    std::vector<float> embeddingBuffer(embeddingBufferSize);
-    size_t embeddingDim;
+        std::vector<float> embeddingBuffer(embeddingBufferSize);
+        size_t embeddingDim;
 
-    int result = cactus_embed(this->_model, text.c_str(), embeddingBuffer.data(), embeddingBufferSize * sizeof(float), &embeddingDim);
+        int result =
+            cactus_embed(this->_model, text.c_str(), embeddingBuffer.data(),
+                         embeddingBufferSize * sizeof(float), &embeddingDim);
 
-    if (result < 0) {
-      throw std::runtime_error("Cactus embedding failed");
-    }
+        if (result < 0) {
+          throw std::runtime_error("Cactus embedding failed");
+        }
 
-    embeddingBuffer.resize(embeddingDim);
+        embeddingBuffer.resize(embeddingDim);
 
-    return std::vector<double>(embeddingBuffer.begin(), embeddingBuffer.end());
-  });
+        return std::vector<double>(embeddingBuffer.begin(),
+                                   embeddingBuffer.end());
+      });
 }
 
 std::shared_ptr<Promise<void>> HybridCactus::reset() {
@@ -102,9 +116,7 @@ std::shared_ptr<Promise<void>> HybridCactus::reset() {
 }
 
 std::shared_ptr<Promise<void>> HybridCactus::stop() {
-  return Promise<void>::async([this]() -> void {
-    cactus_stop(this->_model);
-  });
+  return Promise<void>::async([this]() -> void { cactus_stop(this->_model); });
 }
 
 std::shared_ptr<Promise<void>> HybridCactus::destroy() {

package/cpp/HybridCactus.hpp

@@ -5,26 +5,33 @@
 
 #include <mutex>
 
-namespace margelo::nitro::cactus
-{
+namespace margelo::nitro::cactus {
 
-class HybridCactus : public HybridCactusSpec
-{
+class HybridCactus : public HybridCactusSpec {
 public:
   HybridCactus();
-  
-  std::shared_ptr<Promise<void>> init(const std::string &modelPath, double contextSize) override;
-  
-  std::shared_ptr<Promise<std::string>> complete(const std::string &messagesJson, double responseBufferSize, const std::optional<std::string> &optionsJson, const std::optional<std::string> &toolsJson, const std::optional<std::function<void(const std::string & /* token */, double /* tokenId */)>> &callback) override;
-  
-  std::shared_ptr<Promise<std::vector<double>>> embed(const std::string &text, double embeddingBufferSize) override;
-  
+
+  std::shared_ptr<Promise<void>>
+  init(const std::string &modelPath, double contextSize,
+       const std::optional<std::string> &corpusDir) override;
+
+  std::shared_ptr<Promise<std::string>> complete(
+      const std::string &messagesJson, double responseBufferSize,
+      const std::optional<std::string> &optionsJson,
+      const std::optional<std::string> &toolsJson,
+      const std::optional<std::function<void(const std::string & /* token */,
+                                             double /* tokenId */)>> &callback)
+      override;
+
+  std::shared_ptr<Promise<std::vector<double>>>
+  embed(const std::string &text, double embeddingBufferSize) override;
+
   std::shared_ptr<Promise<void>> reset() override;
-  
+
   std::shared_ptr<Promise<void>> stop() override;
-  
+
   std::shared_ptr<Promise<void>> destroy() override;
-  
+
 private:
   cactus_model_t _model = nullptr;
   size_t _contextSize;