cactus-react-native 0.2.11 → 1.0.2

package/src/classes/CactusLM.ts

@@ -0,0 +1,205 @@
+import { Cactus, CactusFileSystem } from '../native';
+import type {
+  CactusLMDownloadParams,
+  CactusLMCompleteParams,
+  CactusLMCompleteResult,
+  CactusLMEmbedParams,
+  CactusLMEmbedResult,
+  CactusLMGetModelsParams,
+  CactusLMParams,
+} from '../types/CactusLM';
+import type { CactusModel } from '../types/CactusModel';
+import { Telemetry } from '../telemetry/Telemetry';
+import { CactusConfig } from '../config/CactusConfig';
+import { Database } from '../api/Database';
+import { getErrorMessage } from '../utils/error';
+
+export class CactusLM {
+  private readonly cactus = new Cactus();
+
+  private readonly model: string;
+  private readonly contextSize: number;
+  private readonly corpusDir?: string;
+
+  private isDownloading = false;
+  private isInitialized = false;
+  private isGenerating = false;
+
+  private static readonly defaultModel = 'qwen3-0.6';
+  private static readonly defaultContextSize = 2048;
+  private static readonly defaultCompleteOptions = {
+    maxTokens: 512,
+  };
+  private static readonly defaultEmbedBufferSize = 2048;
+
+  private static readonly modelsInfoPath = 'models/info.json';
+
+  constructor({ model, contextSize, corpusDir }: CactusLMParams = {}) {
+    this.model = model ?? CactusLM.defaultModel;
+    this.contextSize = contextSize ?? CactusLM.defaultContextSize;
+    this.corpusDir = corpusDir;
+  }
+
+  public async download({
+    onProgress,
+  }: CactusLMDownloadParams = {}): Promise<void> {
+    if (this.isDownloading) {
+      throw new Error('CactusLM is already downloading');
+    }
+
+    if (await CactusFileSystem.modelExists(this.model)) {
+      onProgress?.(1.0);
+      return;
+    }
+
+    this.isDownloading = true;
+    try {
+      await CactusFileSystem.downloadModel(this.model, onProgress);
+      await this.getModels({ forceRefresh: true });
+    } finally {
+      this.isDownloading = false;
+    }
+  }
+
+  public async init(): Promise<void> {
+    if (this.isInitialized) {
+      return;
+    }
+
+    if (!Telemetry.isInitialized()) {
+      await Telemetry.init(CactusConfig.telemetryToken);
+    }
+
+    if (!(await CactusFileSystem.modelExists(this.model))) {
+      throw new Error(`Model "${this.model}" is not downloaded`);
+    }
+
+    const modelPath = await CactusFileSystem.getModelPath(this.model);
+
+    try {
+      await this.cactus.init(modelPath, this.contextSize, this.corpusDir);
+      Telemetry.logInit(this.model, true);
+      this.isInitialized = true;
+    } catch (error) {
+      Telemetry.logInit(this.model, false, getErrorMessage(error));
+      throw error;
+    }
+  }
+
+  public async complete({
+    messages,
+    options,
+    tools,
+    onToken,
+  }: CactusLMCompleteParams): Promise<CactusLMCompleteResult> {
+    if (this.isGenerating) {
+      throw new Error('CactusLM is already generating');
+    }
+
+    await this.init();
+
+    options = { ...CactusLM.defaultCompleteOptions, ...options };
+    const responseBufferSize =
+      8 * (options.maxTokens ?? CactusLM.defaultCompleteOptions.maxTokens) +
+      256;
+
+    this.isGenerating = true;
+    try {
+      const result = await this.cactus.complete(
+        messages,
+        responseBufferSize,
+        options,
+        tools,
+        onToken
+      );
+      Telemetry.logCompletion(
+        this.model,
+        result.success,
+        result.success ? undefined : result.response,
+        result
+      );
+      return result;
+    } catch (error) {
+      Telemetry.logCompletion(this.model, false, getErrorMessage(error));
+      throw error;
+    } finally {
+      this.isGenerating = false;
+    }
+  }
+
+  public async embed({
+    text,
+  }: CactusLMEmbedParams): Promise<CactusLMEmbedResult> {
+    if (this.isGenerating) {
+      throw new Error('CactusLM is already generating');
+    }
+
+    await this.init();
+
+    this.isGenerating = true;
+    try {
+      const embedding = await this.cactus.embed(
+        text,
+        CactusLM.defaultEmbedBufferSize
+      );
+      Telemetry.logEmbedding(this.model, true);
+      return { embedding };
+    } catch (error) {
+      Telemetry.logEmbedding(this.model, false, getErrorMessage(error));
+      throw error;
+    } finally {
+      this.isGenerating = false;
+    }
+  }
+
+  public stop(): Promise<void> {
+    return this.cactus.stop();
+  }
+
+  public async reset(): Promise<void> {
+    await this.stop();
+    return this.cactus.reset();
+  }
+
+  public async destroy(): Promise<void> {
+    if (!this.isInitialized) {
+      return;
+    }
+
+    await this.stop();
+    await this.cactus.destroy();
+
+    this.isInitialized = false;
+  }
+
+  public async getModels({
+    forceRefresh = false,
+  }: CactusLMGetModelsParams = {}): Promise<CactusModel[]> {
+    if (
+      !forceRefresh &&
+      (await CactusFileSystem.fileExists(CactusLM.modelsInfoPath))
+    ) {
+      try {
+        return JSON.parse(
+          await CactusFileSystem.readFile(CactusLM.modelsInfoPath)
+        );
+      } catch {
+        // Delete corrupted models info
+        await CactusFileSystem.deleteFile(CactusLM.modelsInfoPath);
+      }
+    }
+
+    const models = await Database.getModels();
+
+    for (const model of models) {
+      model.isDownloaded = await CactusFileSystem.modelExists(model.slug);
+    }
+
+    await CactusFileSystem.writeFile(
+      CactusLM.modelsInfoPath,
+      JSON.stringify(models)
+    );
+
+    return models;
+  }
+}

package/src/config/CactusConfig.ts

@@ -0,0 +1,4 @@
+export class CactusConfig {
+  public static telemetryToken?: string;
+  public static isTelemetryEnabled: boolean = true;
+}

package/src/constants/packageVersion.ts

@@ -0,0 +1 @@
+export const packageVersion = '1.0.2';

package/src/hooks/useCactusLM.ts

@@ -0,0 +1,285 @@
+import { useCallback, useEffect, useState, useRef } from 'react';
+import { CactusLM } from '../classes/CactusLM';
+import { CactusFileSystem } from '../native';
+import { getErrorMessage } from '../utils/error';
+import type {
+  CactusLMParams,
+  CactusLMCompleteResult,
+  CactusLMEmbedParams,
+  CactusLMEmbedResult,
+  CactusLMGetModelsParams,
+  CactusLMCompleteParams,
+  CactusLMDownloadParams,
+} from '../types/CactusLM';
+import type { CactusModel } from '../types/CactusModel';
+
+export const useCactusLM = ({
+  model = 'qwen3-0.6',
+  contextSize = 2048,
+  corpusDir = undefined,
+}: CactusLMParams = {}) => {
+  const [cactusLM, setCactusLM] = useState(
+    () => new CactusLM({ model, contextSize, corpusDir })
+  );
+
+  // State
+  const [completion, setCompletion] = useState('');
+  const [isGenerating, setIsGenerating] = useState(false);
+  const [isInitializing, setIsInitializing] = useState(false);
+  const [isDownloaded, setIsDownloaded] = useState(false);
+  const [isDownloading, setIsDownloading] = useState(false);
+  const [downloadProgress, setDownloadProgress] = useState(0);
+  const [error, setError] = useState<string | null>(null);
+
+  const currentModelRef = useRef(model);
+  const currentDownloadIdRef = useRef(0);
+
+  useEffect(() => {
+    currentModelRef.current = model;
+  }, [model]);
+
+  useEffect(() => {
+    setCactusLM(new CactusLM({ model, contextSize, corpusDir }));
+
+    setCompletion('');
+    setIsGenerating(false);
+    setIsInitializing(false);
+    setIsDownloaded(false);
+    setIsDownloading(false);
+    setDownloadProgress(0);
+    setError(null);
+
+    let mounted = true;
+    CactusFileSystem.modelExists(model)
+      .then((exists) => {
+        if (!mounted) {
+          return;
+        }
+        setIsDownloaded(exists);
+      })
+      .catch((e) => {
+        if (!mounted) {
+          return;
+        }
+        setIsDownloaded(false);
+        setError(getErrorMessage(e));
+      });
+
+    return () => {
+      mounted = false;
+    };
+  }, [model, contextSize, corpusDir]);
+
+  useEffect(() => {
+    return () => {
+      cactusLM.destroy().catch(() => {});
+    };
+  }, [cactusLM]);
+
+  const download = useCallback(
+    async ({ onProgress }: CactusLMDownloadParams = {}) => {
+      if (isDownloading) {
+        const message = 'CactusLM is already downloading';
+        setError(message);
+        throw new Error(message);
+      }
+
+      const thisModel = currentModelRef.current;
+      const thisDownloadId = ++currentDownloadIdRef.current;
+
+      setError(null);
+      setDownloadProgress(0);
+      setIsDownloading(true);
+      try {
+        await cactusLM.download({
+          onProgress: (progress) => {
+            if (
+              currentModelRef.current !== thisModel ||
+              currentDownloadIdRef.current !== thisDownloadId
+            ) {
+              return;
+            }
+
+            setDownloadProgress(progress);
+            onProgress?.(progress);
+          },
+        });
+
+        if (
+          currentModelRef.current !== thisModel ||
+          currentDownloadIdRef.current !== thisDownloadId
+        ) {
+          return;
+        }
+
+        setIsDownloaded(true);
+      } catch (e) {
+        if (
+          currentModelRef.current !== thisModel ||
+          currentDownloadIdRef.current !== thisDownloadId
+        ) {
+          return;
+        }
+
+        setError(getErrorMessage(e));
+        throw e;
+      } finally {
+        if (
+          currentModelRef.current !== thisModel ||
+          currentDownloadIdRef.current !== thisDownloadId
+        ) {
+          return;
+        }
+
+        setIsDownloading(false);
+        setDownloadProgress(0);
+      }
+    },
+    [cactusLM, isDownloading]
+  );
+
+  const init = useCallback(async () => {
+    if (isInitializing) {
+      const message = 'CactusLM is already initializing';
+      setError(message);
+      throw new Error(message);
+    }
+
+    setError(null);
+    setIsInitializing(true);
+    try {
+      await cactusLM.init();
+    } catch (e) {
+      setError(getErrorMessage(e));
+      throw e;
+    } finally {
+      setIsInitializing(false);
+    }
+  }, [cactusLM, isInitializing]);
+
+  const complete = useCallback(
+    async ({
+      messages,
+      options,
+      tools,
+      onToken,
+    }: CactusLMCompleteParams): Promise<CactusLMCompleteResult> => {
+      if (isGenerating) {
+        const message = 'CactusLM is already generating';
+        setError(message);
+        throw new Error(message);
+      }
+
+      setError(null);
+      setCompletion('');
+      setIsGenerating(true);
+      try {
+        return await cactusLM.complete({
+          messages,
+          options,
+          tools,
+          onToken: (token) => {
+            setCompletion((prev) => prev + token);
+            onToken?.(token);
+          },
+        });
+      } catch (e) {
+        setError(getErrorMessage(e));
+        throw e;
+      } finally {
+        setIsGenerating(false);
+      }
+    },
+    [cactusLM, isGenerating]
+  );
+
+  const embed = useCallback(
+    async ({ text }: CactusLMEmbedParams): Promise<CactusLMEmbedResult> => {
+      if (isGenerating) {
+        const message = 'CactusLM is already generating';
+        setError(message);
+        throw new Error(message);
+      }
+
+      setError(null);
+      setIsGenerating(true);
+      try {
+        return await cactusLM.embed({ text });
+      } catch (e) {
+        setError(getErrorMessage(e));
+        throw e;
+      } finally {
+        setIsGenerating(false);
+      }
+    },
+    [cactusLM, isGenerating]
+  );
+
+  const stop = useCallback(async () => {
+    setError(null);
+    try {
+      await cactusLM.stop();
+    } catch (e) {
+      setError(getErrorMessage(e));
+      throw e;
+    }
+  }, [cactusLM]);
+
+  const reset = useCallback(async () => {
+    setError(null);
+    try {
+      await cactusLM.reset();
+    } catch (e) {
+      setError(getErrorMessage(e));
+      throw e;
+    } finally {
+      setCompletion('');
+    }
+  }, [cactusLM]);
+
+  const destroy = useCallback(async () => {
+    setError(null);
+    try {
+      await cactusLM.destroy();
+    } catch (e) {
+      setError(getErrorMessage(e));
+      throw e;
+    } finally {
+      setCompletion('');
+    }
+  }, [cactusLM]);
+
+  const getModels = useCallback(
+    async ({ forceRefresh }: CactusLMGetModelsParams = {}): Promise<
+      CactusModel[]
+    > => {
+      setError(null);
+      try {
+        return await cactusLM.getModels({ forceRefresh });
+      } catch (e) {
+        setError(getErrorMessage(e));
+        throw e;
+      }
+    },
+    [cactusLM]
+  );
+
+  return {
+    completion,
+    isGenerating,
+    isInitializing,
+    isDownloaded,
+    isDownloading,
+    downloadProgress,
+    error,
+
+    download,
+    init,
+    complete,
+    embed,
+    reset,
+    stop,
+    destroy,
+    getModels,
+  };
+};

package/src/index.tsx

@@ -0,0 +1,23 @@
+// Classes
+export { CactusLM } from './classes/CactusLM';
+
+// Hooks
+export { useCactusLM } from './hooks/useCactusLM';
+
+// Types
+export type { CactusModel } from './types/CactusModel';
+export type {
+  CactusLMParams,
+  CactusLMDownloadParams,
+  Message,
+  Options,
+  Tool,
+  CactusLMCompleteParams,
+  CactusLMCompleteResult,
+  CactusLMEmbedParams,
+  CactusLMEmbedResult,
+  CactusLMGetModelsParams,
+} from './types/CactusLM';
+
+// Config
+export { CactusConfig } from './config/CactusConfig';

package/src/native/Cactus.ts

@@ -0,0 +1,83 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type { Cactus as CactusSpec } from '../specs/Cactus.nitro';
+import type {
+  CactusLMCompleteResult,
+  Message,
+  Options,
+  Tool,
+} from '../types/CactusLM';
+
+export class Cactus {
+  private readonly hybridCactus =
+    NitroModules.createHybridObject<CactusSpec>('Cactus');
+
+  public init(
+    modelPath: string,
+    contextSize: number,
+    corpusDir?: string
+  ): Promise<void> {
+    return this.hybridCactus.init(modelPath, contextSize, corpusDir);
+  }
+
+  public async complete(
+    messages: Message[],
+    responseBufferSize: number,
+    options?: Options,
+    tools?: Tool[],
+    callback?: (token: string, tokenId: number) => void
+  ): Promise<CactusLMCompleteResult> {
+    const messagesJson = JSON.stringify(messages);
+    const optionsJson = options
+      ? JSON.stringify({
+          temperature: options.temperature,
+          top_p: options.topP,
+          top_k: options.topK,
+          max_tokens: options.maxTokens,
+          stop_sequences: options.stopSequences,
+        })
+      : undefined;
+    const toolsJson = JSON.stringify(tools);
+
+    const response = await this.hybridCactus.complete(
+      messagesJson,
+      responseBufferSize,
+      optionsJson,
+      toolsJson,
+      callback
+    );
+
+    try {
+      const parsed = JSON.parse(response);
+
+      return {
+        success: parsed.success,
+        response: parsed.response,
+        functionCalls: parsed.function_calls,
+        timeToFirstTokenMs: parsed.time_to_first_token_ms,
+        totalTimeMs: parsed.total_time_ms,
+        tokensPerSecond: parsed.tokens_per_second,
+        prefillTokens: parsed.prefill_tokens,
+        decodeTokens: parsed.decode_tokens,
+        totalTokens: parsed.total_tokens,
+      };
+    } catch {
+      throw new Error('Unable to parse completion response');
+    }
+  }
+
+  public embed(text: string, embeddingBufferSize: number): Promise<number[]> {
+    return this.hybridCactus.embed(text, embeddingBufferSize);
+  }
+
+  public reset(): Promise<void> {
+    return this.hybridCactus.reset();
+  }
+
+  public stop(): Promise<void> {
+    return this.hybridCactus.stop();
+  }
+
+  public destroy(): Promise<void> {
+    return this.hybridCactus.destroy();
+  }
+}

package/src/native/CactusCrypto.ts

@@ -0,0 +1,11 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type { CactusCrypto as CactusCryptoSpec } from '../specs/CactusCrypto.nitro';
+
+export class CactusCrypto {
+  private static readonly hybridCactusCrypto =
+    NitroModules.createHybridObject<CactusCryptoSpec>('CactusCrypto');
+
+  public static uuidv5(namespaceUuid: string, name: string): Promise<string> {
+    return this.hybridCactusCrypto.uuidv5(namespaceUuid, name);
+  }
+}

package/src/native/CactusDeviceInfo.ts

@@ -0,0 +1,18 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type {
+  CactusDeviceInfo as CactusDeviceInfoSpec,
+  DeviceInfo,
+} from '../specs/CactusDeviceInfo.nitro';
+
+export class CactusDeviceInfo {
+  private static readonly hybridCactusDeviceInfo =
+    NitroModules.createHybridObject<CactusDeviceInfoSpec>('CactusDeviceInfo');
+
+  public static getAppIdentifier(): Promise<string | undefined> {
+    return this.hybridCactusDeviceInfo.getAppIdentifier();
+  }
+
+  public static getDeviceInfo(): Promise<DeviceInfo> {
+    return this.hybridCactusDeviceInfo.getDeviceInfo();
+  }
+}

package/src/native/CactusFileSystem.ts

@@ -0,0 +1,47 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type { CactusFileSystem as CactusFileSystemSpec } from '../specs/CactusFileSystem.nitro';
+
+export class CactusFileSystem {
+  private static readonly hybridCactusFileSystem =
+    NitroModules.createHybridObject<CactusFileSystemSpec>('CactusFileSystem');
+
+  public static getCactusDirectory(): Promise<string> {
+    return this.hybridCactusFileSystem.getCactusDirectory();
+  }
+
+  public static fileExists(path: string): Promise<boolean> {
+    return this.hybridCactusFileSystem.fileExists(path);
+  }
+
+  public static writeFile(path: string, content: string): Promise<void> {
+    return this.hybridCactusFileSystem.writeFile(path, content);
+  }
+
+  public static readFile(path: string): Promise<string> {
+    return this.hybridCactusFileSystem.readFile(path);
+  }
+
+  public static deleteFile(path: string): Promise<void> {
+    return this.hybridCactusFileSystem.deleteFile(path);
+  }
+
+  public static modelExists(model: string): Promise<boolean> {
+    return this.hybridCactusFileSystem.modelExists(model);
+  }
+
+  public static getModelPath(model: string): Promise<string> {
+    return this.hybridCactusFileSystem.getModelPath(model);
+  }
+
+  public static downloadModel(
+    model: string,
+    onProgress?: (progress: number) => void
+  ): Promise<void> {
+    const from = `https://vlqqczxwyaodtcdmdmlw.supabase.co/storage/v1/object/public/cactus-models/${model}.zip`;
+    return this.hybridCactusFileSystem.downloadModel(model, from, onProgress);
+  }
+
+  public static deleteModel(model: string): Promise<void> {
+    return this.hybridCactusFileSystem.deleteModel(model);
+  }
+}

package/src/native/CactusUtil.ts

@@ -0,0 +1,27 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type { CactusUtil as CactusUtilSpec } from '../specs/CactusUtil.nitro';
+import { Platform } from 'react-native';
+import { CactusFileSystem } from './CactusFileSystem';
+
+export class CactusUtil {
+  private static readonly hybridCactusUtil =
+    NitroModules.createHybridObject<CactusUtilSpec>('CactusUtil');
+
+  public static async registerApp(encryptedData: string): Promise<string> {
+    if (Platform.OS === 'android') {
+      const cactusDirectory = await CactusFileSystem.getCactusDirectory();
+      this.hybridCactusUtil.setAndroidDataDirectory(cactusDirectory);
+    }
+
+    return this.hybridCactusUtil.registerApp(encryptedData);
+  }
+
+  public static async getDeviceId(): Promise<string | null> {
+    if (Platform.OS === 'android') {
+      const cactusDirectory = await CactusFileSystem.getCactusDirectory();
+      this.hybridCactusUtil.setAndroidDataDirectory(cactusDirectory);
+    }
+
+    return this.hybridCactusUtil.getDeviceId();
+  }
+}