cactus-react-native 1.2.0 → 1.4.0

package/README.md

@@ -298,6 +298,82 @@ const App = () => {
 };
 ```
 
+### Tokenization
+
+Convert text into tokens using the model's tokenizer.
+
+#### Class
+
+```typescript
+import { CactusLM } from 'cactus-react-native';
+
+const cactusLM = new CactusLM();
+
+const result = await cactusLM.tokenize({ text: 'Hello, World!' });
+console.log('Token IDs:', result.tokens);
+```
+
+#### Hook
+
+```tsx
+import { useCactusLM } from 'cactus-react-native';
+
+const App = () => {
+  const cactusLM = useCactusLM();
+
+  const handleTokenize = async () => {
+    const result = await cactusLM.tokenize({ text: 'Hello, World!' });
+    console.log('Token IDs:', result.tokens);
+  };
+
+  return <Button title="Tokenize" onPress={handleTokenize} />;
+};
+```
+
+### Score Window
+
+Calculate perplexity scores for a window of tokens within a sequence.
+
+#### Class
+
+```typescript
+import { CactusLM } from 'cactus-react-native';
+
+const cactusLM = new CactusLM();
+
+const tokens = [123, 456, 789, 101, 112];
+const result = await cactusLM.scoreWindow({
+  tokens,
+  start: 1,
+  end: 3,
+  context: 2
+});
+console.log('Score:', result.score);
+```
+
+#### Hook
+
+```tsx
+import { useCactusLM } from 'cactus-react-native';
+
+const App = () => {
+  const cactusLM = useCactusLM();
+
+  const handleScoreWindow = async () => {
+    const tokens = [123, 456, 789, 101, 112];
+    const result = await cactusLM.scoreWindow({
+      tokens,
+      start: 1,
+      end: 3,
+      context: 2
+    });
+    console.log('Score:', result.score);
+  };
+
+  return <Button title="Score Window" onPress={handleScoreWindow} />;
+};
+```
+
 ### Embedding
 
 Convert text and images into numerical vector representations that capture semantic meaning, useful for similarity search and semantic understanding.
@@ -423,7 +499,7 @@ The `CactusSTT` class provides audio transcription and audio embedding capabilit
 
 ### Transcription
 
-Transcribe audio files to text with streaming support.
+Transcribe audio to text with streaming support. Accepts either a file path or raw PCM audio samples.
 
 #### Class
 
@@ -434,12 +510,22 @@ const cactusSTT = new CactusSTT({ model: 'whisper-small' });
 
 await cactusSTT.init();
 
+// Transcribe from file path
 const result = await cactusSTT.transcribe({
-  audioFilePath: 'path/to/audio.wav',
+  audio: 'path/to/audio.wav',
   onToken: (token) => console.log('Token:', token)
 });
 
 console.log('Transcription:', result.response);
+
+// Or transcribe from raw PCM samples
+const pcmSamples: number[] = [/* ... */];
+const result2 = await cactusSTT.transcribe({
+  audio: pcmSamples,
+  onToken: (token) => console.log('Token:', token)
+});
+
+console.log('Transcription:', result2.response);
 ```
 
 #### Hook
@@ -451,10 +537,17 @@ const App = () => {
   const cactusSTT = useCactusSTT({ model: 'whisper-small' });
 
   const handleTranscribe = async () => {
+    // Transcribe from file path
     const result = await cactusSTT.transcribe({
-      audioFilePath: 'path/to/audio.wav',
+      audio: 'path/to/audio.wav',
     });
     console.log('Transcription:', result.response);
+
+    const pcmSamples: number[] = [/* ... */];
+    const result2 = await cactusSTT.transcribe({
+      audio: pcmSamples,
+    });
+    console.log('Transcription:', result2.response);
   };
 
   return (
@@ -507,6 +600,251 @@ const App = () => {
 };
 ```
 
+## Vector Index
+
+The `CactusIndex` class provides a vector database for storing and querying embeddings with metadata. Enabling similarity search and retrieval.
+
+### Creating and Initializing an Index
+
+#### Class
+
+```typescript
+import { CactusIndex } from 'cactus-react-native';
+
+const cactusIndex = new CactusIndex('my-index', 1024);
+await cactusIndex.init();
+```
+
+#### Hook
+
+```tsx
+import { useCactusIndex } from 'cactus-react-native';
+
+const App = () => {
+  const cactusIndex = useCactusIndex({
+    name: 'my-index',
+    embeddingDim: 1024
+  });
+
+  const handleInit = async () => {
+    await cactusIndex.init();
+  };
+
+  return <Button title="Initialize Index" onPress={handleInit} />
+};
+```
+
+### Adding Documents
+
+Add documents with their embeddings and metadata to the index.
+
+#### Class
+
+```typescript
+import { CactusIndex } from 'cactus-react-native';
+
+const cactusIndex = new CactusIndex('my-index', 1024);
+await cactusIndex.init();
+
+await cactusIndex.add({
+  ids: [1, 2, 3],
+  documents: ['First document', 'Second document', 'Third document'],
+  embeddings: [
+    [0.1, 0.2, ...],
+    [0.3, 0.4, ...],
+    [0.5, 0.6, ...]
+  ],
+  metadatas: ['metadata1', 'metadata2', 'metadata3']
+});
+```
+
+#### Hook
+
+```tsx
+import { useCactusIndex } from 'cactus-react-native';
+
+const App = () => {
+  const cactusIndex = useCactusIndex({
+    name: 'my-index',
+    embeddingDim: 1024
+  });
+
+  const handleAdd = async () => {
+    await cactusIndex.add({
+      ids: [1, 2, 3],
+      documents: ['First document', 'Second document', 'Third document'],
+      embeddings: [
+        [0.1, 0.2, ...],
+        [0.3, 0.4, ...],
+        [0.5, 0.6, ...]
+      ],
+      metadatas: ['metadata1', 'metadata2', 'metadata3']
+    });
+  };
+
+  return <Button title="Add Documents" onPress={handleAdd} />;
+};
+```
+
+### Querying the Index
+
+Search for similar documents using embedding vectors.
+
+#### Class
+
+```typescript
+import { CactusIndex } from 'cactus-react-native';
+
+const cactusIndex = new CactusIndex('my-index', 1024);
+await cactusIndex.init();
+
+const result = await cactusIndex.query({
+  embeddings: [[0.1, 0.2, ...]],
+  options: {
+    topK: 5,
+    scoreThreshold: 0.7
+  }
+});
+
+console.log('IDs:', result.ids);
+console.log('Scores:', result.scores);
+```
+
+#### Hook
+
+```tsx
+import { useCactusIndex } from 'cactus-react-native';
+
+const App = () => {
+  const cactusIndex = useCactusIndex({
+    name: 'my-index',
+    embeddingDim: 1024
+  });
+
+  const handleQuery = async () => {
+    const result = await cactusIndex.query({
+      embeddings: [[0.1, 0.2, ...]],
+      options: {
+        topK: 5,
+        scoreThreshold: 0.7
+      }
+    });
+    console.log('IDs:', result.ids);
+    console.log('Scores:', result.scores);
+  };
+
+  return <Button title="Query Index" onPress={handleQuery} />;
+};
+```
+
+### Retrieving Documents
+
+Get documents by their IDs.
+
+#### Class
+
+```typescript
+import { CactusIndex } from 'cactus-react-native';
+
+const cactusIndex = new CactusIndex('my-index', 1024);
+await cactusIndex.init();
+
+const result = await cactusIndex.get({ ids: [1, 2, 3] });
+console.log('Documents:', result.documents);
+console.log('Metadatas:', result.metadatas);
+console.log('Embeddings:', result.embeddings);
+```
+
+#### Hook
+
+```tsx
+import { useCactusIndex } from 'cactus-react-native';
+
+const App = () => {
+  const cactusIndex = useCactusIndex({
+    name: 'my-index',
+    embeddingDim: 1024
+  });
+
+  const handleGet = async () => {
+    const result = await cactusIndex.get({ ids: [1, 2, 3] });
+    console.log('Documents:', result.documents);
+    console.log('Metadatas:', result.metadatas);
+    console.log('Embeddings:', result.embeddings);
+  };
+
+  return <Button title="Get Documents" onPress={handleGet} />;
+};
+```
+
+### Deleting Documents
+
+Mark documents as deleted by their IDs.
+
+#### Class
+
+```typescript
+import { CactusIndex } from 'cactus-react-native';
+
+const cactusIndex = new CactusIndex('my-index', 1024);
+await cactusIndex.init();
+
+await cactusIndex.delete({ ids: [1, 2, 3] });
+```
+
+#### Hook
+
+```tsx
+import { useCactusIndex } from 'cactus-react-native';
+
+const App = () => {
+  const cactusIndex = useCactusIndex({
+    name: 'my-index',
+    embeddingDim: 1024
+  });
+
+  const handleDelete = async () => {
+    await cactusIndex.delete({ ids: [1, 2, 3] });
+  };
+
+  return <Button title="Delete Documents" onPress={handleDelete} />;
+};
+```
+
+### Compacting the Index
+
+Optimize the index by removing deleted documents and reorganizing data.
+
+#### Class
+
+```typescript
+import { CactusIndex } from 'cactus-react-native';
+
+const cactusIndex = new CactusIndex('my-index', 1024);
+await cactusIndex.init();
+
+await cactusIndex.compact();
+```
+
+#### Hook
+
+```tsx
+import { useCactusIndex } from 'cactus-react-native';
+
+const App = () => {
+  const cactusIndex = useCactusIndex({
+    name: 'my-index',
+    embeddingDim: 1024
+  });
+
+  const handleCompact = async () => {
+    await cactusIndex.compact();
+  };
+
+  return <Button title="Compact Index" onPress={handleCompact} />;
+};
+```
+
 ## API Reference
 
 ### CactusLM Class
@@ -516,7 +854,7 @@ const App = () => {
 **`new CactusLM(params?: CactusLMParams)`**
 
 **Parameters:**
-- `model` - Model slug (default: `'qwen3-0.6'`).
+- `model` - Model slug or absolute path to Cactus model (default: `'qwen3-0.6'`).
 - `contextSize` - Context window size (default: `2048`).
 - `corpusDir` - Directory containing text files for RAG (default: `undefined`).
 
@@ -545,16 +883,35 @@ Performs text completion with optional streaming and tool support. Automatically
   - `topK` - Top-K sampling limit (default: model-optimized).
   - `maxTokens` - Maximum number of tokens to generate (default: `512`).
   - `stopSequences` - Array of strings to stop generation (default: `undefined`).
+  - `forceTools` - Force the model to call one of the provided tools (default: `false`).
 - `tools` - Array of `Tool` objects for function calling (default: `undefined`).
 - `onToken` - Callback for streaming tokens.
 - `mode` - Completion mode: `'local'` | `'hybrid'` (default: `'local'`)
 
+**`tokenize(params: CactusLMTokenizeParams): Promise<CactusLMTokenizeResult>`**
+
+Converts text into tokens using the model's tokenizer.
+
+**Parameters:**
+- `text` - Text to tokenize.
+
+**`scoreWindow(params: CactusLMScoreWindowParams): Promise<CactusLMScoreWindowResult>`**
+
+Calculates perplexity scores for a window of tokens within a sequence.
+
+**Parameters:**
+- `tokens` - Array of token IDs.
+- `start` - Start index of the window.
+- `end` - End index of the window.
+- `context` - Number of context tokens before the window.
+
 **`embed(params: CactusLMEmbedParams): Promise<CactusLMEmbedResult>`**
 
 Generates embeddings for the given text. Automatically calls `init()` if not already initialized. Throws an error if a generation (completion or embedding) is already in progress.
 
 **Parameters:**
 - `text` - Text to embed.
+- `normalize` - Whether to normalize the embedding vector (default: `false`).
 
 **`imageEmbed(params: CactusLMImageEmbedParams): Promise<CactusLMImageEmbedResult>`**
 
@@ -577,7 +934,7 @@ Releases all resources associated with the model. Automatically calls `stop()` f
 
 **`getModels(): Promise<CactusModel[]>`**
 
-Fetches available models from the database and checks their download status. Results are cached in memory after the first call and subsequent calls return the cached results.
+Fetches available models from the database and checks their download status.
 
 ### useCactusLM Hook
 
@@ -598,12 +955,14 @@ The `useCactusLM` hook manages a `CactusLM` instance with reactive state. When m
 - `download(params?: CactusLMDownloadParams): Promise<void>` - Downloads the model. Updates `isDownloading` and `downloadProgress` state during download. Sets `isDownloaded` to `true` on success.
 - `init(): Promise<void>` - Initializes the model for inference. Sets `isInitializing` to `true` during initialization.
 - `complete(params: CactusLMCompleteParams): Promise<CactusLMCompleteResult>` - Generates text completions. Automatically accumulates tokens in the `completion` state during streaming. Sets `isGenerating` to `true` while generating. Clears `completion` before starting.
+- `tokenize(params: CactusLMTokenizeParams): Promise<CactusLMTokenizeResult>` - Converts text into tokens. Sets `isGenerating` to `true` during operation.
+- `scoreWindow(params: CactusLMScoreWindowParams): Promise<CactusLMScoreWindowResult>` - Calculates perplexity scores for a window of tokens. Sets `isGenerating` to `true` during operation.
 - `embed(params: CactusLMEmbedParams): Promise<CactusLMEmbedResult>` - Generates embeddings for the given text. Sets `isGenerating` to `true` during operation.
 - `imageEmbed(params: CactusLMImageEmbedParams): Promise<CactusLMImageEmbedResult>` - Generates embeddings for the given image. Sets `isGenerating` to `true` while generating.
 - `stop(): Promise<void>` - Stops ongoing generation. Clears any errors.
 - `reset(): Promise<void>` - Resets the model's internal state, clearing cached context. Also clears the `completion` state.
 - `destroy(): Promise<void>` - Releases all resources associated with the model. Clears the `completion` state. Automatically called when the component unmounts.
-- `getModels(): Promise<CactusModel[]>` - Fetches available models from the database and checks their download status. Results are cached in memory and reused on subsequent calls.
+- `getModels(): Promise<CactusModel[]>` - Fetches available models from the database and checks their download status.
 
 ### CactusSTT Class
 
@@ -612,7 +971,7 @@ The `useCactusLM` hook manages a `CactusLM` instance with reactive state. When m
 **`new CactusSTT(params?: CactusSTTParams)`**
 
 **Parameters:**
-- `model` - Model slug (default: `'whisper-small'`).
+- `model` - Model slug or absolute path to Cactus model (default: `'qwen3-0.6'`).
 - `contextSize` - Context window size (default: `2048`).
 
 #### Methods
@@ -630,10 +989,10 @@ Initializes the model and prepares it for inference. Safe to call multiple times
 
 **`transcribe(params: CactusSTTTranscribeParams): Promise<CactusSTTTranscribeResult>`**
 
-Transcribes audio to text with optional streaming support. Automatically calls `init()` if not already initialized. Throws an error if a generation is already in progress.
+Transcribes audio to text with optional streaming support. Accepts either a file path or raw PCM audio samples. Automatically calls `init()` if not already initialized. Throws an error if a generation is already in progress.
 
 **Parameters:**
-- `audioFilePath` - Path to the audio file.
+- `audio` - Path to the audio file or raw PCM samples.
 - `prompt` - Optional prompt to guide transcription (default: `'<|startoftranscript|><|en|><|transcribe|><|notimestamps|>'`).
 - `options` - Transcription options:
   - `temperature` - Sampling temperature (default: model-optimized).
@@ -662,9 +1021,9 @@ Resets the model's internal state. Automatically calls `stop()` first.
 
 Releases all resources associated with the model. Automatically calls `stop()` first. Safe to call even if the model is not initialized.
 
-**`getModels(): Promise<CactusModel[]>`**
+**`getModels(): Promise<CactusSTTModel[]>`**
 
-Fetches available models from the database and checks their download status. Results are cached in memory after the first call and subsequent calls return the cached results.
+Fetches available STT models from the database and checks their download status.
 
 ### useCactusSTT Hook
 
@@ -689,7 +1048,85 @@ The `useCactusSTT` hook manages a `CactusSTT` instance with reactive state. When
 - `stop(): Promise<void>` - Stops ongoing generation. Clears any errors.
 - `reset(): Promise<void>` - Resets the model's internal state. Also clears the `transcription` state.
 - `destroy(): Promise<void>` - Releases all resources associated with the model. Clears the `transcription` state. Automatically called when the component unmounts.
-- `getModels(): Promise<CactusModel[]>` - Fetches available models from the database and checks their download status. Results are cached in memory and reused on subsequent calls.
+- `getModels(): Promise<CactusSTTModel[]>` - Fetches available STT models from the database and checks their download status.
+
+### CactusIndex Class
+
+#### Constructor
+
+**`new CactusIndex(name: string, embeddingDim: number)`**
+
+**Parameters:**
+- `name` - Name of the index.
+- `embeddingDim` - Dimension of the embedding vectors.
+
+#### Methods
+
+**`init(): Promise<void>`**
+
+Initializes the index and prepares it for operations. Must be called before using any other methods.
+
+**`add(params: CactusIndexAddParams): Promise<void>`**
+
+Adds documents with their embeddings and metadata to the index.
+
+**Parameters:**
+- `ids` - Array of document IDs.
+- `documents` - Array of document texts.
+- `embeddings` - Array of embedding vectors (each vector must match `embeddingDim`).
+- `metadatas` - Optional array of metadata strings.
+
+**`query(params: CactusIndexQueryParams): Promise<CactusIndexQueryResult>`**
+
+Searches for similar documents using embedding vectors.
+
+**Parameters:**
+- `embeddings` - Array of query embedding vectors.
+- `options` - Query options:
+  - `topK` - Number of top results to return (default: 10).
+  - `scoreThreshold` - Minimum similarity score threshold (default: -1.0).
+
+**`get(params: CactusIndexGetParams): Promise<CactusIndexGetResult>`**
+
+Retrieves documents by their IDs.
+
+**Parameters:**
+- `ids` - Array of document IDs to retrieve.
+
+**`delete(params: CactusIndexDeleteParams): Promise<void>`**
+
+Deletes documents from the index by their IDs.
+
+**Parameters:**
+- `ids` - Array of document IDs to delete.
+
+**`compact(): Promise<void>`**
+
+Optimizes the index by removing deleted documents and reorganizing data for better performance. Call after a series of deletions.
+
+**`destroy(): Promise<void>`**
+
+Releases all resources associated with the index from memory.
+
+### useCactusIndex Hook
+
+The `useCactusIndex` hook manages a `CactusIndex` instance with reactive state. When index parameters (`name` or `embeddingDim`) change, the hook creates a new instance and resets all state. The hook automatically cleans up resources when the component unmounts.
+
+#### State
+
+- `isInitializing: boolean` - Whether the index is initializing.
+- `isProcessing: boolean` - Whether the index is processing an operation (add, query, get, delete, or compact).
+- `error: string | null` - Last error message from any operation, or `null` if there is no error. Cleared before starting new operations.
+
+#### Methods
+
+- `init(): Promise<void>` - Initializes the index. Sets `isInitializing` to `true` during initialization.
+- `add(params: CactusIndexAddParams): Promise<void>` - Adds documents to the index. Sets `isProcessing` to `true` during operation.
+- `query(params: CactusIndexQueryParams): Promise<CactusIndexQueryResult>` - Searches for similar documents. Sets `isProcessing` to `true` during operation.
+- `get(params: CactusIndexGetParams): Promise<CactusIndexGetResult>` - Retrieves documents by IDs. Sets `isProcessing` to `true` during operation.
+- `delete(params: CactusIndexDeleteParams): Promise<void>` - Deletes documents. Sets `isProcessing` to `true` during operation.
+- `compact(): Promise<void>` - Optimizes the index. Sets `isProcessing` to `true` during operation.
+- `destroy(): Promise<void>` - Releases all resources. Automatically called when the component unmounts.
 
 ## Type Definitions
 
@@ -730,6 +1167,7 @@ interface CompleteOptions {
   topK?: number;
   maxTokens?: number;
   stopSequences?: string[];
+  forceTools?: boolean;
 }
 ```
 
@@ -783,11 +1221,47 @@ interface CactusLMCompleteResult {
 }
 ```
 
+### CactusLMTokenizeParams
+
+```typescript
+interface CactusLMTokenizeParams {
+  text: string;
+}
+```
+
+### CactusLMTokenizeResult
+
+```typescript
+interface CactusLMTokenizeResult {
+  tokens: number[];
+}
+```
+
+### CactusLMScoreWindowParams
+
+```typescript
+interface CactusLMScoreWindowParams {
+  tokens: number[];
+  start: number;
+  end: number;
+  context: number;
+}
+```
+
+### CactusLMScoreWindowResult
+
+```typescript
+interface CactusLMScoreWindowResult {
+  score: number;
+}
+```
+
 ### CactusLMEmbedParams
 
 ```typescript
 interface CactusLMEmbedParams {
   text: string;
+  normalize?: boolean;
 }
 ```
 
@@ -826,6 +1300,19 @@ interface CactusModel {
   downloadUrl: string;
   supportsToolCalling: boolean;
   supportsVision: boolean;
+  supportsCompletion: boolean;
+  createdAt: Date;
+  isDownloaded: boolean;
+}
+```
+
+### CactusSTTModel
+
+```typescript
+interface CactusSTTModel {
+  slug: string;
+  sizeMb: number;
+  downloadUrl: string;
   createdAt: Date;
   isDownloaded: boolean;
 }
@@ -865,7 +1352,7 @@ interface TranscribeOptions {
 
 ```typescript
 interface CactusSTTTranscribeParams {
-  audioFilePath: string;
+  audio: string | number[];
   prompt?: string;
   options?: TranscribeOptions;
   onToken?: (token: string) => void;
@@ -904,6 +1391,79 @@ interface CactusSTTAudioEmbedResult {
 }
 ```
 
+### CactusIndexParams
+
+```typescript
+interface CactusIndexParams {
+  name: string;
+  embeddingDim: number;
+}
+```
+
+### CactusIndexAddParams
+
+```typescript
+interface CactusIndexAddParams {
+  ids: number[];
+  documents: string[];
+  embeddings: number[][];
+  metadatas?: string[];
+}
+```
+
+### CactusIndexGetParams
+
+```typescript
+interface CactusIndexGetParams {
+  ids: number[];
+}
+```
+
+### CactusIndexGetResult
+
+```typescript
+interface CactusIndexGetResult {
+  documents: string[];
+  metadatas: string[];
+  embeddings: number[][];
+}
+```
+
+### IndexQueryOptions
+
+```typescript
+interface IndexQueryOptions {
+  topK?: number;
+  scoreThreshold?: number;
+}
+```
+
+### CactusIndexQueryParams
+
+```typescript
+interface CactusIndexQueryParams {
+  embeddings: number[][];
+  options?: IndexQueryOptions;
+}
+```
+
+### CactusIndexQueryResult
+
+```typescript
+interface CactusIndexQueryResult {
+  ids: number[][];
+  scores: number[][];
+}
+```
+
+### CactusIndexDeleteParams
+
+```typescript
+interface CactusIndexDeleteParams {
+  ids: number[];
+}
+```
+
 ## Configuration
 
 ### Telemetry