@realtimex/sdk 1.0.9 → 1.1.2

package/README.md

@@ -25,6 +25,9 @@ Before using this SDK, ensure your Supabase database is set up:
 import { RealtimeXSDK } from '@realtimex/sdk';
 
 const sdk = new RealtimeXSDK({
+  // Development Mode: Use API key for full access
+  realtimex: { apiKey: 'sk-abc123...' }, 
+  // OR Production Mode: Declare permissions
   permissions: ['activities.read', 'activities.write', 'webhook.trigger']
 });
 
@@ -59,8 +62,9 @@ When you start your Local App from the RealtimeX Main App:
 const sdk = new RealtimeXSDK({
   realtimex: {
     url: 'http://custom-host:3001',  // Default: localhost:3001
-    appId: 'custom-id',               // Override auto-detected
-    appName: 'My App',                // Override auto-detected
+    apiKey: 'sk-abc123...',           // Development mode
+    appId: 'custom-id',               // Production mode (override)
+    appName: 'My App',                // Optional
   }
 });
 ```
@@ -120,6 +124,165 @@ const threads = await sdk.api.getThreads('sales');
 const task = await sdk.api.getTask('task-uuid');
 ```
 
+### LLM Module
+
+Access AI capabilities through the RealtimeX proxy:
+
+```typescript
+const sdk = new RealtimeXSDK({
+  permissions: ['llm.chat', 'llm.embed', 'llm.providers', 'vectors.write', 'vectors.read']
+});
+```
+
+#### List Providers & Models
+
+```typescript
+
+
+// Get only configured Chat providers (recommended)
+const chatRes = await sdk.llm.chatProviders();
+// chatRes.providers: Array of chat providers with models
+
+// Get only configured Embedding providers (recommended)
+const embedRes = await sdk.llm.embedProviders();
+// embedRes.providers: Array of embedding providers with models
+```
+
+
+#### Chat Completion
+
+```typescript
+// Sync Chat
+const response = await sdk.llm.chat(
+  [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'What is RealtimeX?' }
+  ],
+  { 
+    model: 'gpt-4o',           // Optional: specific model
+    provider: 'openai',        // Optional: specific provider
+    temperature: 0.7,          // Optional: 0.0-2.0
+    max_tokens: 1000           // Optional: max response tokens
+  }
+);
+console.log(response.response?.content);
+
+// Streaming Chat
+for await (const chunk of sdk.llm.chatStream(messages, options)) {
+  process.stdout.write(chunk.textResponse || '');
+}
+```
+
+#### Generate Embeddings
+
+```typescript
+const { embeddings, dimensions, provider, model } = await sdk.llm.embed(
+  ['Hello world', 'Goodbye'],
+  { provider: 'openai', model: 'text-embedding-3-small' } // Optional
+);
+// embeddings: number[][] - vector arrays
+// dimensions: number - vector dimension (e.g., 1536)
+```
+
+#### Vector Store Operations
+
+```typescript
+// Upsert vectors with metadata
+await sdk.llm.vectors.upsert([
+  { 
+    id: 'chunk-1', 
+    vector: embeddings[0], 
+    metadata: { 
+      text: 'Hello world',      // Original text (for retrieval)
+      documentId: 'doc-1',       // Logical grouping
+      customField: 'any value'   // Any custom metadata
+    } 
+  }
+], { 
+  workspaceId: 'ws-123'          // Optional: physical namespace isolation
+});
+
+// Query similar vectors
+const results = await sdk.llm.vectors.query(queryVector, {
+  topK: 5,                       // Number of results
+  workspaceId: 'ws-123',         // Optional: search in specific workspace
+  filter: { documentId: 'doc-1' } // Optional: filter by document
+});
+// returns: { success, results: [{ id, score, metadata }] }
+
+// List all workspaces for this app
+const { workspaces } = await sdk.llm.vectors.listWorkspaces();
+// returns: { success, workspaces: ['ws-123', 'default', ...] }
+
+// Delete all vectors in a workspace
+await sdk.llm.vectors.delete({ 
+  deleteAll: true, 
+  workspaceId: 'ws-123' 
+});
+```
+
+#### High-Level Helpers
+
+These combine multiple operations for common RAG patterns:
+
+```typescript
+// embedAndStore: Text → Embed → Store (one call)
+await sdk.llm.embedAndStore(
+  ['Document text 1', 'Document text 2'],  // texts to embed
+  {
+    documentId: 'doc-123',                  // Optional: logical grouping
+    workspaceId: 'ws-456',                  // Optional: physical isolation
+    provider: 'openai',                     // Optional: embedding provider
+    model: 'text-embedding-3-small'         // Optional: embedding model
+  }
+);
+
+// search: Query → Embed → Search (one call)
+const searchResults = await sdk.llm.search(
+  'What is RealtimeX?',                     // search query (text, not vector)
+  {
+    topK: 5,                                // Number of results
+    workspaceId: 'ws-123',                  // Optional: search in workspace
+    documentId: 'doc-1',                    // Optional: filter by document
+    provider: 'openai',                     // Optional: embedding provider
+    model: 'text-embedding-3-small'         // Optional: embedding model
+  }
+);
+// returns: [{ id, score, metadata: { text, documentId, ... } }]
+```
+
+> **Note on Isolation:**
+> - `workspaceId`: Creates **physical namespace** (`sdk_{appId}_{wsId}`) - data completely isolated
+> - `documentId`: Stored as **metadata**, filtered after search (post-filter)
+
+### Error Handling
+
+The SDK provides specific error classes for handling LLM-related issues:
+
+```typescript
+import { LLMPermissionError, LLMProviderError } from '@realtimex/sdk';
+
+try {
+  for await (const chunk of sdk.llm.chatStream(messages)) {
+    process.stdout.write(chunk.textResponse || '');
+  }
+} catch (error) {
+  if (error instanceof LLMPermissionError) {
+    // Permission not granted: 'llm.chat' etc.
+    console.error(`Permission required: ${error.permission}`);
+  } else if (error instanceof LLMProviderError) {
+    // Provider errors: rate limit, timeout, model unavailable, etc.
+    console.error(`Provider error: ${error.message} (code: ${error.code})`);
+    // Common codes: LLM_STREAM_ERROR, RATE_LIMIT, PROVIDER_UNAVAILABLE
+  }
+}
+```
+
+| Error Class | Common Codes | Description |
+|-------------|--------------|-------------|
+| `LLMPermissionError` | `PERMISSION_REQUIRED` | Missing or denied permission |
+| `LLMProviderError` | `LLM_STREAM_ERROR`, `RATE_LIMIT`, `PROVIDER_UNAVAILABLE` | AI provider issues |
+
 ## Environment Variables
 
 | Variable | Description |

package/dist/index.d.mts

@@ -6,6 +6,7 @@ interface SDKConfig {
         url?: string;
         appId?: string;
         appName?: string;
+        apiKey?: string;
     };
     defaultPort?: number;
     permissions?: string[];
@@ -88,7 +89,8 @@ declare class ActivitiesModule {
     private baseUrl;
     private appId;
     private appName;
-    constructor(realtimexUrl: string, appId: string, appName?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
     /**
      * Request a single permission from Electron via internal API
      */
@@ -124,7 +126,8 @@ declare class WebhookModule {
     private realtimexUrl;
     private appName?;
     private appId?;
-    constructor(realtimexUrl: string, appName?: string, appId?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
     /**
      * Request a single permission from Electron via internal API
      */
@@ -160,7 +163,8 @@ declare class ApiModule {
     private realtimexUrl;
     private appId;
     private appName;
-    constructor(realtimexUrl: string, appId: string, appName?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appId: string, appName?: string, apiKey?: string);
     private getHeaders;
     /**
      * Request a single permission from Electron via internal API
@@ -190,7 +194,8 @@ declare class TaskModule {
     private realtimexUrl;
     private appName?;
     private appId?;
-    constructor(realtimexUrl: string, appName?: string, appId?: string);
+    private apiKey?;
+    constructor(realtimexUrl: string, appName?: string, appId?: string, apiKey?: string);
     /**
      * Mark task as processing
      */
@@ -249,6 +254,310 @@ declare class PortModule {
     getPort(): Promise<number>;
 }
 
+/**
+ * LLM Module for RealtimeX SDK
+ *
+ * Provides access to LLM capabilities:
+ * - Chat completion (sync and streaming)
+ * - Embedding generation
+ * - Provider/model listing
+ * - Vector storage (upsert, query, delete)
+ */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface ChatOptions {
+    model?: string;
+    provider?: string;
+    temperature?: number;
+    max_tokens?: number;
+}
+interface ChatResponse {
+    success: boolean;
+    response?: {
+        content: string;
+        model: string;
+        provider?: string;
+        metrics?: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+            duration?: number;
+            outputTps?: number;
+        };
+    };
+    error?: string;
+    code?: string;
+}
+interface StreamChunk {
+    uuid?: string;
+    type?: string;
+    textResponse?: string;
+    close?: boolean;
+    error?: boolean;
+}
+interface EmbedOptions {
+    provider?: string;
+    model?: string;
+}
+interface EmbedResponse {
+    success: boolean;
+    embeddings?: number[][];
+    provider?: string;
+    model?: string;
+    dimensions?: number;
+    error?: string;
+    code?: string;
+    errors?: string[];
+}
+interface Provider {
+    provider: string;
+    models: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+interface ProvidersResponse {
+    success: boolean;
+    llm?: Provider[];
+    embedding?: Provider[];
+    providers?: Provider[];
+    error?: string;
+    code?: string;
+}
+interface VectorRecord {
+    id: string;
+    vector: number[];
+    metadata?: {
+        text?: string;
+        documentId?: string;
+        workspaceId?: string;
+        [key: string]: unknown;
+    };
+}
+interface VectorUpsertOptions {
+    workspaceId?: string;
+}
+interface VectorUpsertResponse {
+    success: boolean;
+    upserted?: number;
+    namespace?: string;
+    error?: string;
+    code?: string;
+    errors?: string[];
+}
+interface VectorQueryOptions {
+    topK?: number;
+    filter?: {
+        workspaceId?: string;
+        documentId?: string;
+    };
+    workspaceId?: string;
+    provider?: string;
+    model?: string;
+}
+interface VectorQueryResult {
+    id: string;
+    score: number;
+    metadata?: {
+        text?: string;
+        documentId?: string;
+        workspaceId?: string;
+        [key: string]: unknown;
+    };
+}
+interface VectorQueryResponse {
+    success: boolean;
+    results?: VectorQueryResult[];
+    error?: string;
+    code?: string;
+}
+interface VectorDeleteOptions {
+    workspaceId?: string;
+    deleteAll: true;
+}
+interface VectorDeleteResponse {
+    success: boolean;
+    deleted?: number;
+    message?: string;
+    error?: string;
+    code?: string;
+    errors?: string[];
+}
+interface VectorListWorkspacesResponse {
+    success: boolean;
+    workspaces?: string[];
+    error?: string;
+    code?: string;
+}
+declare class LLMPermissionError extends Error {
+    permission: string;
+    code: string;
+    constructor(permission: string, code?: string);
+}
+declare class LLMProviderError extends Error {
+    code: string;
+    constructor(message: string, code?: string);
+}
+declare class VectorStore {
+    private baseUrl;
+    private appId;
+    private apiKey?;
+    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
+    private get headers();
+    /**
+     * Upsert (insert or update) vectors into storage
+     *
+     * @example
+     * ```ts
+     * await sdk.llm.vectors.upsert([
+     *   { id: 'chunk-1', vector: embeddings[0], metadata: { text: 'Hello', documentId: 'doc-1' } }
+     * ], { workspaceId: 'ws-123' });
+     * ```
+     */
+    upsert(vectors: VectorRecord[], options?: VectorUpsertOptions): Promise<VectorUpsertResponse>;
+    /**
+     * Query similar vectors by embedding
+     *
+     * @example
+     * ```ts
+     * const results = await sdk.llm.vectors.query(queryVector, {
+     *   topK: 5,
+     *   filter: { documentId: 'doc-1' },
+     *   workspaceId: 'ws-123'
+     * });
+     * ```
+     */
+    query(vector: number[], options?: VectorQueryOptions): Promise<VectorQueryResponse>;
+    /**
+     * Delete vectors from storage
+     *
+     * Note: Currently only supports deleteAll: true
+     * Use workspaceId to scope deletion to a specific workspace
+     *
+     * @example
+     * ```ts
+     * await sdk.llm.vectors.delete({ deleteAll: true, workspaceId: 'ws-123' });
+     * ```
+     */
+    delete(options: VectorDeleteOptions): Promise<VectorDeleteResponse>;
+    /**
+     * List all available workspaces (namespaces) for this app
+     *
+     * @example
+     * ```ts
+     * const { workspaces } = await sdk.llm.vectors.listWorkspaces();
+     * console.log('Workspaces:', workspaces);
+     * ```
+     */
+    listWorkspaces(): Promise<VectorListWorkspacesResponse>;
+}
+declare class LLMModule {
+    private baseUrl;
+    private appId;
+    private apiKey?;
+    vectors: VectorStore;
+    constructor(baseUrl: string, appId: string, apiKey?: string | undefined);
+    private get headers();
+    /**
+     * Get only configured chat (LLM) providers
+     *
+     * @example
+     * ```ts
+     * const { providers } = await sdk.llm.chatProviders();
+     * console.log('Available chat models:', providers[0].models);
+     * ```
+     */
+    chatProviders(): Promise<ProvidersResponse>;
+    /**
+     * Get only configured embedding providers
+     *
+     * @example
+     * ```ts
+     * const { providers } = await sdk.llm.embedProviders();
+     * console.log('Available embedding models:', providers[0].models);
+     * ```
+     */
+    embedProviders(): Promise<ProvidersResponse>;
+    /**
+     * Send a chat completion request (synchronous)
+     *
+     * @example
+     * ```ts
+     * const response = await sdk.llm.chat([
+     *   { role: 'system', content: 'You are a helpful assistant.' },
+     *   { role: 'user', content: 'Hello!' }
+     * ], { model: 'gpt-4o', temperature: 0.7 });
+     *
+     * console.log(response.response?.content);
+     * ```
+     */
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Send a streaming chat completion request (SSE)
+     *
+     * @example
+     * ```ts
+     * for await (const chunk of sdk.llm.chatStream([
+     *   { role: 'user', content: 'Tell me a story' }
+     * ])) {
+     *   process.stdout.write(chunk.textResponse || '');
+     * }
+     * ```
+     */
+    chatStream(messages: ChatMessage[], options?: ChatOptions): AsyncGenerator<StreamChunk, void, unknown>;
+    /**
+     * Generate vector embeddings from text
+     *
+     * @example
+     * ```ts
+     * // Single text
+     * const { embeddings } = await sdk.llm.embed('Hello world');
+     *
+     * // Multiple texts
+     * const { embeddings } = await sdk.llm.embed(['Hello', 'World']);
+     * ```
+     */
+    embed(input: string | string[], options?: EmbedOptions): Promise<EmbedResponse>;
+    /**
+     * Helper: Embed text and store as vectors in one call
+     *
+     * @example
+     * ```ts
+     * await sdk.llm.embedAndStore({
+     *   texts: ['Hello world', 'Goodbye world'],
+     *   documentId: 'doc-123',
+     *   workspaceId: 'ws-456'
+     * });
+     * ```
+     */
+    embedAndStore(params: {
+        texts: string[];
+        documentId?: string;
+        workspaceId?: string;
+        idPrefix?: string;
+        provider?: string;
+        model?: string;
+    }): Promise<VectorUpsertResponse>;
+    /**
+     * Helper: Search similar documents by text query
+     *
+     * @example
+     * ```ts
+     * const results = await sdk.llm.search('What is RealtimeX?', {
+     *   topK: 5,
+     *   workspaceId: 'ws-123'
+     * });
+     *
+     * for (const result of results) {
+     *   console.log(result.metadata?.text, result.score);
+     * }
+     * ```
+     */
+    search(query: string, options?: VectorQueryOptions): Promise<VectorQueryResult[]>;
+}
+
 /**
  * RealtimeX Local App SDK
  *
@@ -262,8 +571,10 @@ declare class RealtimeXSDK {
     api: ApiModule;
     task: TaskModule;
     port: PortModule;
+    llm: LLMModule;
     readonly appId: string;
     readonly appName: string | undefined;
+    readonly apiKey: string | undefined;
     private readonly realtimexUrl;
     private readonly permissions;
     private static DEFAULT_REALTIMEX_URL;
@@ -277,6 +588,16 @@ declare class RealtimeXSDK {
      * Get environment variable (works in Node.js and browser)
      */
     private getEnvVar;
+    /**
+     * Ping RealtimeX server to verify connection and authentication.
+     * Works in both development (API Key) and production (App ID) modes.
+     */
+    ping(): Promise<{
+        success: boolean;
+        mode: 'development' | 'production';
+        appId?: string;
+        timestamp: string;
+    }>;
 }
 
-export { ActivitiesModule, type Activity, type Agent, ApiModule, PermissionDeniedError, PermissionRequiredError, PortModule, RealtimeXSDK, type SDKConfig, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, WebhookModule, type Workspace };
+export { ActivitiesModule, type Activity, type Agent, ApiModule, type ChatMessage, type ChatOptions, type ChatResponse, type EmbedOptions, type EmbedResponse, LLMModule, LLMPermissionError, LLMProviderError, PermissionDeniedError, PermissionRequiredError, PortModule, type Provider, type ProvidersResponse, RealtimeXSDK, type SDKConfig, type StreamChunk, type Task, TaskModule, type TaskRun, type Thread, type TriggerAgentPayload, type TriggerAgentResponse, type VectorDeleteOptions, type VectorDeleteResponse, type VectorQueryOptions, type VectorQueryResponse, type VectorQueryResult, type VectorRecord, VectorStore, type VectorUpsertOptions, type VectorUpsertResponse, WebhookModule, type Workspace };