cactus-react-native 1.2.1 → 1.4.0

package/nitrogen/generated/shared/c++/HybridCactusIndexSpec.cpp

@@ -0,0 +1,27 @@
+///
+/// HybridCactusIndexSpec.cpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+#include "HybridCactusIndexSpec.hpp"
+
+namespace margelo::nitro::cactus {
+
+  void HybridCactusIndexSpec::loadHybridMethods() {
+    // load base methods/properties
+    HybridObject::loadHybridMethods();
+    // load custom methods/properties
+    registerHybrids(this, [](Prototype& prototype) {
+      prototype.registerHybridMethod("init", &HybridCactusIndexSpec::init);
+      prototype.registerHybridMethod("add", &HybridCactusIndexSpec::add);
+      prototype.registerHybridMethod("_delete", &HybridCactusIndexSpec::_delete);
+      prototype.registerHybridMethod("get", &HybridCactusIndexSpec::get);
+      prototype.registerHybridMethod("query", &HybridCactusIndexSpec::query);
+      prototype.registerHybridMethod("compact", &HybridCactusIndexSpec::compact);
+      prototype.registerHybridMethod("destroy", &HybridCactusIndexSpec::destroy);
+    });
+  }
+
+} // namespace margelo::nitro::cactus

package/nitrogen/generated/shared/c++/HybridCactusIndexSpec.hpp

@@ -0,0 +1,76 @@
+///
+/// HybridCactusIndexSpec.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/HybridObject.hpp>)
+#include <NitroModules/HybridObject.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `CactusIndexGetResult` to properly resolve imports.
+namespace margelo::nitro::cactus { struct CactusIndexGetResult; }
+// Forward declaration of `CactusIndexQueryResult` to properly resolve imports.
+namespace margelo::nitro::cactus { struct CactusIndexQueryResult; }
+
+#include <NitroModules/Promise.hpp>
+#include <string>
+#include <vector>
+#include <optional>
+#include "CactusIndexGetResult.hpp"
+#include "CactusIndexQueryResult.hpp"
+
+namespace margelo::nitro::cactus {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for `CactusIndex`
+   * Inherit this class to create instances of `HybridCactusIndexSpec` in C++.
+   * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
+   * @example
+   * ```cpp
+   * class HybridCactusIndex: public HybridCactusIndexSpec {
+   * public:
+   *   HybridCactusIndex(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * ```
+   */
+  class HybridCactusIndexSpec: public virtual HybridObject {
+    public:
+      // Constructor
+      explicit HybridCactusIndexSpec(): HybridObject(TAG) { }
+
+      // Destructor
+      ~HybridCactusIndexSpec() override = default;
+
+    public:
+      // Properties
+      
+
+    public:
+      // Methods
+      virtual std::shared_ptr<Promise<void>> init(const std::string& indexPath, double embeddingDim) = 0;
+      virtual std::shared_ptr<Promise<void>> add(const std::vector<double>& ids, const std::vector<std::string>& documents, const std::vector<std::vector<double>>& embeddings, const std::optional<std::vector<std::string>>& metadatas) = 0;
+      virtual std::shared_ptr<Promise<void>> _delete(const std::vector<double>& ids) = 0;
+      virtual std::shared_ptr<Promise<CactusIndexGetResult>> get(const std::vector<double>& ids) = 0;
+      virtual std::shared_ptr<Promise<CactusIndexQueryResult>> query(const std::vector<std::vector<double>>& embeddings, const std::optional<std::string>& optionsJson) = 0;
+      virtual std::shared_ptr<Promise<void>> compact() = 0;
+      virtual std::shared_ptr<Promise<void>> destroy() = 0;
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "CactusIndex";
+  };
+
+} // namespace margelo::nitro::cactus

package/nitrogen/generated/shared/c++/HybridCactusSpec.cpp

@@ -2,7 +2,7 @@
 /// HybridCactusSpec.cpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
-/// Copyright © 2025 Marc Rousavy @ Margelo
+/// Copyright © 2026 Marc Rousavy @ Margelo
 ///
 
 #include "HybridCactusSpec.hpp"
@@ -16,6 +16,8 @@ namespace margelo::nitro::cactus {
     registerHybrids(this, [](Prototype& prototype) {
       prototype.registerHybridMethod("init", &HybridCactusSpec::init);
       prototype.registerHybridMethod("complete", &HybridCactusSpec::complete);
+      prototype.registerHybridMethod("tokenize", &HybridCactusSpec::tokenize);
+      prototype.registerHybridMethod("scoreWindow", &HybridCactusSpec::scoreWindow);
       prototype.registerHybridMethod("transcribe", &HybridCactusSpec::transcribe);
       prototype.registerHybridMethod("embed", &HybridCactusSpec::embed);
       prototype.registerHybridMethod("imageEmbed", &HybridCactusSpec::imageEmbed);

package/nitrogen/generated/shared/c++/HybridCactusSpec.hpp

@@ -2,7 +2,7 @@
 /// HybridCactusSpec.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
-/// Copyright © 2025 Marc Rousavy @ Margelo
+/// Copyright © 2026 Marc Rousavy @ Margelo
 ///
 
 #pragma once
@@ -20,6 +20,7 @@
 #include <optional>
 #include <functional>
 #include <vector>
+#include <variant>
 
 namespace margelo::nitro::cactus {
 
@@ -54,8 +55,10 @@ namespace margelo::nitro::cactus {
       // Methods
       virtual std::shared_ptr<Promise<void>> init(const std::string& modelPath, double contextSize, const std::optional<std::string>& corpusDir) = 0;
       virtual 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) = 0;
-      virtual std::shared_ptr<Promise<std::string>> transcribe(const std::string& audioFilePath, const std::string& prompt, double responseBufferSize, const std::optional<std::string>& optionsJson, const std::optional<std::function<void(const std::string& /* token */, double /* tokenId */)>>& callback) = 0;
-      virtual std::shared_ptr<Promise<std::vector<double>>> embed(const std::string& text, double embeddingBufferSize) = 0;
+      virtual std::shared_ptr<Promise<std::vector<double>>> tokenize(const std::string& text) = 0;
+      virtual std::shared_ptr<Promise<std::string>> scoreWindow(const std::vector<double>& tokens, double start, double end, double context) = 0;
+      virtual std::shared_ptr<Promise<std::string>> transcribe(const std::variant<std::vector<double>, std::string>& audio, const std::string& prompt, double responseBufferSize, const std::optional<std::string>& optionsJson, const std::optional<std::function<void(const std::string& /* token */, double /* tokenId */)>>& callback) = 0;
+      virtual std::shared_ptr<Promise<std::vector<double>>> embed(const std::string& text, double embeddingBufferSize, bool normalize) = 0;
       virtual std::shared_ptr<Promise<std::vector<double>>> imageEmbed(const std::string& imagePath, double embeddingBufferSize) = 0;
       virtual std::shared_ptr<Promise<std::vector<double>>> audioEmbed(const std::string& audioPath, double embeddingBufferSize) = 0;
       virtual std::shared_ptr<Promise<void>> reset() = 0;

package/nitrogen/generated/shared/c++/HybridCactusUtilSpec.cpp

@@ -2,7 +2,7 @@
 /// HybridCactusUtilSpec.cpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
-/// Copyright © 2025 Marc Rousavy @ Margelo
+/// Copyright © 2026 Marc Rousavy @ Margelo
 ///
 
 #include "HybridCactusUtilSpec.hpp"

package/nitrogen/generated/shared/c++/HybridCactusUtilSpec.hpp

@@ -2,7 +2,7 @@
 /// HybridCactusUtilSpec.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
-/// Copyright © 2025 Marc Rousavy @ Margelo
+/// Copyright © 2026 Marc Rousavy @ Margelo
 ///
 
 #pragma once
@@ -51,7 +51,7 @@ namespace margelo::nitro::cactus {
     public:
       // Methods
       virtual std::shared_ptr<Promise<std::string>> registerApp(const std::string& encryptedData) = 0;
-      virtual std::shared_ptr<Promise<std::optional<std::string>>> getDeviceId() = 0;
+      virtual std::shared_ptr<Promise<std::optional<std::string>>> getDeviceId(const std::optional<std::string>& token) = 0;
       virtual std::shared_ptr<Promise<void>> setAndroidDataDirectory(const std::string& dataDir) = 0;
 
     protected:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cactus-react-native",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Run AI models locally on mobile devices",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -83,7 +83,7 @@
     "react": "19.1.0",
     "react-native": "0.81.1",
     "react-native-builder-bob": "^0.40.14",
-    "react-native-nitro-modules": "^0.31.3",
+    "react-native-nitro-modules": "^0.31.10",
     "release-it": "^19.0.4",
     "turbo": "^2.5.6",
     "typescript": "^5.9.2"

package/src/api/Database.ts

@@ -4,6 +4,7 @@ import type { LogRecord } from '../telemetry/Telemetry';
 import { packageVersion } from '../constants/packageVersion';
 import type { CactusModel } from '../types/CactusModel';
 import type { CactusSTTModel } from '../types/CactusSTTModel';
+import { CactusConfig } from '../config/CactusConfig';
 
 interface CactusModelResponse {
   name: string;
@@ -47,12 +48,23 @@ export class Database {
     }
   }
 
-  public static async registerDevice(device_data: DeviceInfo): Promise<string> {
+  public static async registerDevice({
+    deviceData,
+    deviceId,
+  }: {
+    deviceData?: DeviceInfo;
+    deviceId?: string;
+  }): Promise<string> {
     const response = await fetch(
       `${this.url}/functions/v1/device-registration`,
       {
         method: 'POST',
-        body: JSON.stringify({ device_data }),
+        body: JSON.stringify({
+          device_data: deviceData,
+          device_id: deviceId,
+          cactus_pro_key: CactusConfig.cactusProKey,
+        }),
+        headers: { 'Content-Type': 'application/json' },
       }
     );
 

package/src/classes/CactusIndex.ts

@@ -0,0 +1,58 @@
+import { CactusIndex as NativeCactusIndex, CactusFileSystem } from '../native';
+import type {
+  CactusIndexAddParams,
+  CactusIndexGetParams,
+  CactusIndexGetResult,
+  CactusIndexQueryParams,
+  CactusIndexQueryResult,
+  CactusIndexDeleteParams,
+} from '../types/CactusIndex';
+
+export class CactusIndex {
+  private readonly cactusIndex = new NativeCactusIndex();
+
+  private readonly name: string;
+  private readonly embeddingDim: number;
+
+  constructor(name: string, embeddingDim: number) {
+    this.name = name;
+    this.embeddingDim = embeddingDim;
+  }
+
+  public async init(): Promise<void> {
+    const indexPath = await CactusFileSystem.getIndexPath(this.name);
+    return this.cactusIndex.init(indexPath, this.embeddingDim);
+  }
+
+  public add({
+    ids,
+    documents,
+    embeddings,
+    metadatas,
+  }: CactusIndexAddParams): Promise<void> {
+    return this.cactusIndex.add(ids, documents, embeddings, metadatas);
+  }
+
+  public delete({ ids }: CactusIndexDeleteParams): Promise<void> {
+    return this.cactusIndex.delete(ids);
+  }
+
+  public get({ ids }: CactusIndexGetParams): Promise<CactusIndexGetResult> {
+    return this.cactusIndex.get(ids);
+  }
+
+  public query({
+    embeddings,
+    options,
+  }: CactusIndexQueryParams): Promise<CactusIndexQueryResult> {
+    return this.cactusIndex.query(embeddings, options);
+  }
+
+  public compact(): Promise<void> {
+    return this.cactusIndex.compact();
+  }
+
+  public destroy(): Promise<void> {
+    return this.cactusIndex.destroy();
+  }
+}

package/src/classes/CactusLM.ts

@@ -3,6 +3,10 @@ import type {
   CactusLMDownloadParams,
   CactusLMCompleteParams,
   CactusLMCompleteResult,
+  CactusLMTokenizeParams,
+  CactusLMTokenizeResult,
+  CactusLMScoreWindowParams,
+  CactusLMScoreWindowResult,
   CactusLMEmbedParams,
   CactusLMEmbedResult,
   CactusLMImageEmbedParams,
@@ -46,6 +50,11 @@ export class CactusLM {
   public async download({
     onProgress,
   }: CactusLMDownloadParams = {}): Promise<void> {
+    if (this.isModelPath(this.model)) {
+      onProgress?.(1.0);
+      return;
+    }
+
     if (this.isDownloading) {
       throw new Error('CactusLM is already downloading');
     }
@@ -73,12 +82,16 @@ export class CactusLM {
       return;
     }
 
-    if (!(await CactusFileSystem.modelExists(this.model))) {
-      throw new Error(`Model "${this.model}" is not downloaded`);
+    let modelPath: string;
+    if (this.isModelPath(this.model)) {
+      modelPath = this.model.replace('file://', '');
+    } else {
+      if (!(await CactusFileSystem.modelExists(this.model))) {
+        throw new Error(`Model "${this.model}" is not downloaded`);
+      }
+      modelPath = await CactusFileSystem.getModelPath(this.model);
     }
 
-    const modelPath = await CactusFileSystem.getModelPath(this.model);
-
     try {
       await this.cactus.init(modelPath, this.contextSize, this.corpusDir);
       Telemetry.logInit(this.model, true);
@@ -153,8 +166,26 @@ export class CactusLM {
     }
   }
 
+  public async tokenize({
+    text,
+  }: CactusLMTokenizeParams): Promise<CactusLMTokenizeResult> {
+    return { tokens: await this.cactus.tokenize(text) };
+  }
+
+  public async scoreWindow({
+    tokens,
+    start,
+    end,
+    context,
+  }: CactusLMScoreWindowParams): Promise<CactusLMScoreWindowResult> {
+    return {
+      score: await this.cactus.scoreWindow(tokens, start, end, context),
+    };
+  }
+
   public async embed({
     text,
+    normalize = false,
   }: CactusLMEmbedParams): Promise<CactusLMEmbedResult> {
     if (this.isGenerating) {
       throw new Error('CactusLM is already generating');
@@ -166,7 +197,8 @@ export class CactusLM {
     try {
       const embedding = await this.cactus.embed(
         text,
-        CactusLM.defaultEmbedBufferSize
+        CactusLM.defaultEmbedBufferSize,
+        normalize
       );
       Telemetry.logEmbedding(this.model, true);
       return { embedding };
@@ -230,4 +262,8 @@ export class CactusLM {
     }
     return models;
   }
+
+  private isModelPath(model: string): boolean {
+    return model.startsWith('file://') || model.startsWith('/');
+  }
 }

package/src/classes/CactusSTT.ts

@@ -42,6 +42,11 @@ export class CactusSTT {
   public async download({
     onProgress,
   }: CactusSTTDownloadParams = {}): Promise<void> {
+    if (this.isModelPath(this.model)) {
+      onProgress?.(1.0);
+      return;
+    }
+
     if (this.isDownloading) {
       throw new Error('CactusSTT is already downloading');
     }
@@ -69,12 +74,16 @@ export class CactusSTT {
       return;
     }
 
-    if (!(await CactusFileSystem.modelExists(this.model))) {
-      throw new Error(`Model "${this.model}" is not downloaded`);
+    let modelPath: string;
+    if (this.isModelPath(this.model)) {
+      modelPath = this.model.replace('file://', '');
+    } else {
+      if (!(await CactusFileSystem.modelExists(this.model))) {
+        throw new Error(`Model "${this.model}" is not downloaded`);
+      }
+      modelPath = await CactusFileSystem.getModelPath(this.model);
     }
 
-    const modelPath = await CactusFileSystem.getModelPath(this.model);
-
     try {
       await this.cactus.init(modelPath, this.contextSize);
       Telemetry.logInit(this.model, true);
@@ -86,7 +95,7 @@ export class CactusSTT {
   }
 
   public async transcribe({
-    audioFilePath,
+    audio,
     prompt,
     options,
     onToken,
@@ -107,7 +116,7 @@ export class CactusSTT {
     this.isGenerating = true;
     try {
       const result = await this.cactus.transcribe(
-        audioFilePath,
+        audio,
         prompt,
         responseBufferSize,
         options,
@@ -180,4 +189,8 @@ export class CactusSTT {
     }
     return models;
   }
+
+  private isModelPath(model: string): boolean {
+    return model.startsWith('file://') || model.startsWith('/');
+  }
 }

package/src/config/CactusConfig.ts

@@ -5,4 +5,7 @@ export class CactusConfig {
 
   // Hybrid mode
   public static cactusToken?: string;
+
+  // Pro features
+  public static cactusProKey?: string;
 }

package/src/constants/packageVersion.ts

@@ -1 +1 @@
-export const packageVersion = '1.2.1';
+export const packageVersion = '1.4.0';

package/src/hooks/useCactusIndex.ts

@@ -0,0 +1,195 @@
+import { useCallback, useEffect, useState } from 'react';
+import { CactusIndex } from '../classes/CactusIndex';
+import { getErrorMessage } from '../utils/error';
+import type {
+  CactusIndexParams,
+  CactusIndexAddParams,
+  CactusIndexGetParams,
+  CactusIndexGetResult,
+  CactusIndexQueryParams,
+  CactusIndexQueryResult,
+  CactusIndexDeleteParams,
+} from '../types/CactusIndex';
+
+export const useCactusIndex = ({ name, embeddingDim }: CactusIndexParams) => {
+  const [cactusIndex, setCactusIndex] = useState(
+    () => new CactusIndex(name, embeddingDim)
+  );
+
+  // State
+  const [isInitializing, setIsInitializing] = useState(false);
+  const [isProcessing, setIsProcessing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setCactusIndex(new CactusIndex(name, embeddingDim));
+
+    setIsInitializing(false);
+    setIsProcessing(false);
+    setError(null);
+  }, [name, embeddingDim]);
+
+  useEffect(() => {
+    return () => {
+      cactusIndex.destroy().catch(() => {});
+    };
+  }, [cactusIndex]);
+
+  const init = useCallback(async () => {
+    if (isInitializing) {
+      const message = 'CactusIndex is already initializing';
+      setError(message);
+      throw new Error(message);
+    }
+
+    setError(null);
+    setIsInitializing(true);
+    try {
+      await cactusIndex.init();
+    } catch (e) {
+      setError(getErrorMessage(e));
+      throw e;
+    } finally {
+      setIsInitializing(false);
+    }
+  }, [cactusIndex, isInitializing]);
+
+  const add = useCallback(
+    async ({
+      ids,
+      documents,
+      metadatas,
+      embeddings,
+    }: CactusIndexAddParams): Promise<void> => {
+      if (isProcessing) {
+        const message = 'CactusIndex is already processing';
+        setError(message);
+        throw new Error(message);
+      }
+
+      setError(null);
+      setIsProcessing(true);
+      try {
+        await cactusIndex.add({ ids, documents, metadatas, embeddings });
+      } catch (e) {
+        setError(getErrorMessage(e));
+        throw e;
+      } finally {
+        setIsProcessing(false);
+      }
+    },
+    [cactusIndex, isProcessing]
+  );
+
+  const _delete = useCallback(
+    async ({ ids }: CactusIndexDeleteParams): Promise<void> => {
+      if (isProcessing) {
+        const message = 'CactusIndex is already processing';
+        setError(message);
+        throw new Error(message);
+      }
+
+      setError(null);
+      setIsProcessing(true);
+      try {
+        await cactusIndex.delete({ ids });
+      } catch (e) {
+        setError(getErrorMessage(e));
+        throw e;
+      } finally {
+        setIsProcessing(false);
+      }
+    },
+    [cactusIndex, isProcessing]
+  );
+
+  const get = useCallback(
+    async ({ ids }: CactusIndexGetParams): Promise<CactusIndexGetResult> => {
+      if (isProcessing) {
+        const message = 'CactusIndex is already processing';
+        setError(message);
+        throw new Error(message);
+      }
+
+      setError(null);
+      setIsProcessing(true);
+      try {
+        return await cactusIndex.get({ ids });
+      } catch (e) {
+        setError(getErrorMessage(e));
+        throw e;
+      } finally {
+        setIsProcessing(false);
+      }
+    },
+    [cactusIndex, isProcessing]
+  );
+
+  const query = useCallback(
+    async ({
+      embeddings,
+      options,
+    }: CactusIndexQueryParams): Promise<CactusIndexQueryResult> => {
+      if (isProcessing) {
+        const message = 'CactusIndex is already processing';
+        setError(message);
+        throw new Error(message);
+      }
+
+      setError(null);
+      setIsProcessing(true);
+      try {
+        return await cactusIndex.query({ embeddings, options });
+      } catch (e) {
+        setError(getErrorMessage(e));
+        throw e;
+      } finally {
+        setIsProcessing(false);
+      }
+    },
+    [cactusIndex, isProcessing]
+  );
+
+  const compact = useCallback(async () => {
+    if (isProcessing) {
+      const message = 'CactusIndex is already processing';
+      setError(message);
+      throw new Error(message);
+    }
+
+    setError(null);
+    setIsProcessing(true);
+    try {
+      await cactusIndex.compact();
+    } catch (e) {
+      setError(getErrorMessage(e));
+      throw e;
+    } finally {
+      setIsProcessing(false);
+    }
+  }, [cactusIndex, isProcessing]);
+
+  const destroy = useCallback(async () => {
+    setError(null);
+    try {
+      await cactusIndex.destroy();
+    } catch (e) {
+      setError(getErrorMessage(e));
+      throw e;
+    }
+  }, [cactusIndex]);
+
+  return {
+    isInitializing,
+    isProcessing,
+    error,
+
+    init,
+    add,
+    delete: _delete,
+    get,
+    query,
+    compact,
+    destroy,
+  };
+};