cactus-react-native 1.2.1 → 1.5.0

package/README.md

@@ -78,6 +78,32 @@ const App = () => {
 
 ## Language Model
 
+### Model Options
+
+Choose model quantization and NPU acceleration with Pro models.
+
+```typescript
+import { CactusLM } from 'cactus-react-native';
+
+// Use int4 for faster performance and smaller file size
+const cactusLM = new CactusLM({
+  model: 'lfm2-vl-450m',
+  options: {
+    quantization: 'int4', // 'int4' or 'int8'
+    pro: false
+  }
+});
+
+// Use pro models for NPU acceleration
+const cactusPro = new CactusLM({
+  model: 'lfm2-vl-450m',
+  options: {
+    quantization: 'int4',
+    pro: true
+  }
+});
+```
+
 ### Completion
 
 Generate text responses from the model by providing a conversation history.
@@ -298,6 +324,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 +525,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 +536,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 +563,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 (
@@ -466,6 +585,60 @@ const App = () => {
 };
 ```
 
+### Streaming Transcription
+
+Transcribe audio in real-time with incremental results.
+
+#### Class
+
+```typescript
+import { CactusSTT } from 'cactus-react-native';
+
+const cactusSTT = new CactusSTT({ model: 'whisper-small' });
+
+await cactusSTT.streamTranscribeInit();
+
+const audioChunk: number[] = [/* PCM samples */];
+await cactusSTT.streamTranscribeInsert({ audio: audioChunk });
+
+const result = await cactusSTT.streamTranscribeProcess({
+  options: { confirmationThreshold: 0.95 }
+});
+
+console.log('Confirmed:', result.confirmed);
+console.log('Pending:', result.pending);
+
+const final = await cactusSTT.streamTranscribeFinalize();
+await cactusSTT.streamTranscribeDestroy();
+```
+
+#### Hook
+
+```tsx
+import { useCactusSTT } from 'cactus-react-native';
+
+const App = () => {
+  const cactusSTT = useCactusSTT({ model: 'whisper-small' });
+
+  const handleStream = async () => {
+    await cactusSTT.streamTranscribeInit();
+
+    const audioChunk: number[] = [/* PCM samples */];
+    await cactusSTT.streamTranscribeInsert({ audio: audioChunk });
+
+    await cactusSTT.streamTranscribeProcess();
+  };
+
+  return (
+    <>
+      <Button onPress={handleStream} title="Stream" />
+      <Text>{cactusSTT.streamTranscribeConfirmed}</Text>
+      <Text>{cactusSTT.streamTranscribePending}</Text>
+    </>
+  );
+};
+```
+
 ### Audio Embedding
 
 Generate embeddings from audio files for audio understanding.
@@ -507,6 +680,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,9 +934,12 @@ 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.6b'`).
 - `contextSize` - Context window size (default: `2048`).
 - `corpusDir` - Directory containing text files for RAG (default: `undefined`).
+- `options` - Model options for quantization and NPU acceleration:
+  - `quantization` - Quantization type: `'int4'` | `'int8'` (default: `'int4'`).
+  - `pro` - Enable NPU-accelerated models (default: `false`).
 
 #### Methods
 
@@ -545,16 +966,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>`**
 
@@ -575,13 +1015,13 @@ Resets the model's internal state, clearing any cached context. Automatically ca
 
 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(): CactusModel[]`**
 
-Fetches available models from the database and checks their download status.
+Returns available models.
 
 ### 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.
+The `useCactusLM` hook manages a `CactusLM` instance with reactive state. When model parameters (`model`, `contextSize`, `corpusDir`, `options`) change, the hook creates a new instance and resets all state. The hook automatically cleans up resources when the component unmounts.
 
 #### State
 
@@ -598,12 +1038,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.
+- `getModels(): CactusModel[]` - Returns available models.
 
 ### CactusSTT Class
 
@@ -612,8 +1054,11 @@ 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: `'whisper-small'`).
 - `contextSize` - Context window size (default: `2048`).
+- `options` - Model options for quantization and NPU acceleration:
+  - `quantization` - Quantization type: `'int4'` | `'int8'` (default: `'int4'`).
+  - `pro` - Enable NPU-accelerated models (default: `false`).
 
 #### Methods
 
@@ -630,10 +1075,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).
@@ -650,6 +1095,33 @@ Generates embeddings for the given audio file. Automatically calls `init()` if n
 **Parameters:**
 - `audioPath` - Path to the audio file.
 
+**`streamTranscribeInit(): Promise<void>`**
+
+Initializes a streaming transcription session. Automatically calls `init()` if not already initialized.
+
+**`streamTranscribeInsert(params: CactusSTTStreamTranscribeInsertParams): Promise<void>`**
+
+Inserts PCM audio samples into the streaming buffer.
+
+**Parameters:**
+- `audio` - Array of PCM audio samples.
+
+**`streamTranscribeProcess(params?: CactusSTTStreamTranscribeProcessParams): Promise<CactusSTTStreamTranscribeProcessResult>`**
+
+Processes accumulated audio and returns incremental transcription results.
+
+**Parameters:**
+- `options` - Processing options:
+  - `confirmationThreshold` - Confidence threshold for confirming text.
+
+**`streamTranscribeFinalize(): Promise<CactusSTTStreamTranscribeFinalizeResult>`**
+
+Finalizes the streaming session and returns remaining transcription text.
+
+**`streamTranscribeDestroy(): Promise<void>`**
+
+Destroys the streaming session and releases resources.
+
 **`stop(): Promise<void>`**
 
 Stops ongoing transcription or embedding generation.
@@ -662,18 +1134,21 @@ 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<CactusSTTModel[]>`**
+**`getModels(): CactusModel[]`**
 
-Fetches available STT models from the database and checks their download status.
+Returns available speech-to-text models.
 
 ### useCactusSTT Hook
 
-The `useCactusSTT` hook manages a `CactusSTT` instance with reactive state. When model parameters (`model`, `contextSize`) change, the hook creates a new instance and resets all state. The hook automatically cleans up resources when the component unmounts.
+The `useCactusSTT` hook manages a `CactusSTT` instance with reactive state. When model parameters (`model`, `contextSize`, `options`) change, the hook creates a new instance and resets all state. The hook automatically cleans up resources when the component unmounts.
 
 #### State
 
 - `transcription: string` - Current transcription text. Automatically accumulated during streaming. Cleared before each new transcription and when calling `reset()` or `destroy()`.
+- `streamTranscribeConfirmed: string` - Accumulated confirmed text from streaming transcription.
+- `streamTranscribePending: string` - Current pending text from streaming transcription.
 - `isGenerating: boolean` - Whether the model is currently generating (transcription or embedding). Both operations share this flag.
+- `isStreamTranscribing: boolean` - Whether a streaming transcription session is active.
 - `isInitializing: boolean` - Whether the model is initializing.
 - `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.
@@ -686,10 +1161,93 @@ The `useCactusSTT` hook manages a `CactusSTT` instance with reactive state. When
 - `init(): Promise<void>` - Initializes the model for inference. Sets `isInitializing` to `true` during initialization.
 - `transcribe(params: CactusSTTTranscribeParams): Promise<CactusSTTTranscribeResult>` - Transcribes audio to text. Automatically accumulates tokens in the `transcription` state during streaming. Sets `isGenerating` to `true` while generating. Clears `transcription` before starting.
 - `audioEmbed(params: CactusSTTAudioEmbedParams): Promise<CactusSTTAudioEmbedResult>` - Generates embeddings for the given audio. Sets `isGenerating` to `true` during operation.
+- `streamTranscribeInit(): Promise<void>` - Initializes a streaming transcription session. Sets `isStreamTranscribing` to `true`.
+- `streamTranscribeInsert(params: CactusSTTStreamTranscribeInsertParams): Promise<void>` - Inserts audio chunks into the streaming buffer.
+- `streamTranscribeProcess(params?: CactusSTTStreamTranscribeProcessParams): Promise<CactusSTTStreamTranscribeProcessResult>` - Processes audio and returns results. Automatically accumulates confirmed text in `streamTranscribeConfirmed` and updates `streamTranscribePending`.
+- `streamTranscribeFinalize(): Promise<CactusSTTStreamTranscribeFinalizeResult>` - Finalizes streaming and returns remaining text.
+- `streamTranscribeDestroy(): Promise<void>` - Destroys the streaming session. Sets `isStreamTranscribing` to `false`.
 - `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<CactusSTTModel[]>` - Fetches available STT models from the database and checks their download status.
+- `getModels(): CactusModel[]` - Returns available speech-to-text models.
+
+### 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
 
@@ -700,6 +1258,7 @@ interface CactusLMParams {
   model?: string;
   contextSize?: number;
   corpusDir?: string;
+  options?: ModelOptions;
 }
 ```
 
@@ -730,6 +1289,7 @@ interface CompleteOptions {
   topK?: number;
   maxTokens?: number;
   stopSequences?: string[];
+  forceTools?: boolean;
 }
 ```
 
@@ -783,11 +1343,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;
 }
 ```
 
@@ -819,28 +1415,36 @@ interface CactusLMImageEmbedResult {
 
 ```typescript
 interface CactusModel {
-  name: string;
-  slug: string;
-  quantization: number;
-  sizeMb: number;
-  downloadUrl: string;
-  supportsToolCalling: boolean;
-  supportsVision: boolean;
-  supportsCompletion: boolean;
-  createdAt: Date;
-  isDownloaded: boolean;
+  completion: boolean;
+  tools: boolean;
+  vision: boolean;
+  embed: boolean;
+  speech: boolean;
+  quantization: {
+    int4: {
+      sizeMb: number;
+      url: string;
+      pro?: {
+        apple: string;
+      };
+    };
+    int8: {
+      sizeMb: number;
+      url: string;
+      pro?: {
+        apple: string;
+      };
+    };
+  };
 }
 ```
 
-### CactusSTTModel
+### ModelOptions
 
 ```typescript
-interface CactusSTTModel {
-  slug: string;
-  sizeMb: number;
-  downloadUrl: string;
-  createdAt: Date;
-  isDownloaded: boolean;
+interface ModelOptions {
+  quantization: 'int4' | 'int8';
+  pro: boolean;
 }
 ```
 
@@ -850,6 +1454,7 @@ interface CactusSTTModel {
 interface CactusSTTParams {
   model?: string;
   contextSize?: number;
+  options?: ModelOptions;
 }
 ```
 
@@ -878,7 +1483,7 @@ interface TranscribeOptions {
 
 ```typescript
 interface CactusSTTTranscribeParams {
-  audioFilePath: string;
+  audio: string | number[];
   prompt?: string;
   options?: TranscribeOptions;
   onToken?: (token: string) => void;
@@ -917,6 +1522,122 @@ interface CactusSTTAudioEmbedResult {
 }
 ```
 
+### CactusSTTStreamTranscribeInsertParams
+
+```typescript
+interface CactusSTTStreamTranscribeInsertParams {
+  audio: number[];
+}
+```
+
+### StreamTranscribeProcessOptions
+
+```typescript
+interface StreamTranscribeProcessOptions {
+  confirmationThreshold?: number;
+}
+```
+
+### CactusSTTStreamTranscribeProcessParams
+
+```typescript
+interface CactusSTTStreamTranscribeProcessParams {
+  options?: StreamTranscribeProcessOptions;
+}
+```
+
+### CactusSTTStreamTranscribeProcessResult
+
+```typescript
+interface CactusSTTStreamTranscribeProcessResult {
+  success: boolean;
+  confirmed: string;
+  pending: string;
+}
+```
+
+### CactusSTTStreamTranscribeFinalizeResult
+
+```typescript
+interface CactusSTTStreamTranscribeFinalizeResult {
+  success: boolean;
+  confirmed: string;
+}
+```
+
+### 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
@@ -944,6 +1665,17 @@ import { CactusConfig } from 'cactus-react-native';
 CactusConfig.cactusToken = 'your-cactus-token-here';
 ```
 
+### Cactus Pro
+
+Enable NPU-accelerated models for enhanced performance.
+
+```typescript
+import { CactusConfig } from 'cactus-react-native';
+
+// Set your Cactus Pro key
+CactusConfig.cactusProKey = 'your-cactus-pro-key-here';
+```
+
 ## Performance Tips
 
 - **Model Selection** - Choose smaller models for faster inference on mobile devices.