@realtimex/sdk 1.0.9 → 1.1.1

package/dist/index.mjs

@@ -429,6 +429,384 @@ var PortModule = class {
   }
 };
 
+// src/modules/llm.ts
+var LLMPermissionError = class extends Error {
+  constructor(permission, code = "PERMISSION_REQUIRED") {
+    super(`Permission required: ${permission}`);
+    this.permission = permission;
+    this.code = code;
+    this.name = "LLMPermissionError";
+  }
+};
+var LLMProviderError = class extends Error {
+  constructor(message, code = "LLM_ERROR") {
+    super(message);
+    this.code = code;
+    this.name = "LLMProviderError";
+  }
+};
+var VectorStore = class {
+  constructor(baseUrl, appId) {
+    this.baseUrl = baseUrl;
+    this.appId = appId;
+  }
+  get headers() {
+    return {
+      "Content-Type": "application/json",
+      "x-app-id": this.appId
+    };
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async upsert(vectors, options = {}) {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/upsert`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({
+        vectors,
+        workspaceId: options.workspaceId
+      })
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "vectors.write");
+    }
+    return data;
+  }
+  /**
+   * Query similar vectors by embedding
+   * 
+   * @example
+   * ```ts
+   * const results = await sdk.llm.vectors.query(queryVector, {
+   *   topK: 5,
+   *   filter: { documentId: 'doc-1' },
+   *   workspaceId: 'ws-123'
+   * });
+   * ```
+   */
+  async query(vector, options = {}) {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/query`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({
+        vector,
+        topK: options.topK ?? 5,
+        filter: options.filter,
+        workspaceId: options.workspaceId
+      })
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "vectors.read");
+    }
+    return data;
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async delete(options) {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/delete`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify(options)
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "vectors.write");
+    }
+    return data;
+  }
+  /**
+   * List all available workspaces (namespaces) for this app
+   * 
+   * @example
+   * ```ts
+   * const { workspaces } = await sdk.llm.vectors.listWorkspaces();
+   * console.log('Workspaces:', workspaces);
+   * ```
+   */
+  async listWorkspaces() {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/vectors/workspaces`, {
+      method: "GET",
+      headers: this.headers
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "vectors.read");
+    }
+    return data;
+  }
+};
+var LLMModule = class {
+  constructor(baseUrl, appId) {
+    this.baseUrl = baseUrl;
+    this.appId = appId;
+    this.vectors = new VectorStore(baseUrl, appId);
+  }
+  get headers() {
+    return {
+      "Content-Type": "application/json",
+      "x-app-id": this.appId
+    };
+  }
+  /**
+   * Get available LLM and embedding providers/models
+   * 
+   * @example
+   * ```ts
+   * const { llm, embedding } = await sdk.llm.getProviders();
+   * console.log('Available LLM models:', llm[0].models);
+   * ```
+   */
+  async getProviders() {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/providers`, {
+      method: "GET",
+      headers: this.headers
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "llm.providers");
+    }
+    return data;
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async chat(messages, options = {}) {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/chat`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({
+        messages,
+        model: options.model,
+        provider: options.provider,
+        temperature: options.temperature ?? 0.7,
+        max_tokens: options.max_tokens ?? 1e3
+      })
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "llm.chat");
+    }
+    if (data.code === "LLM_ERROR") {
+      throw new LLMProviderError(data.error || "LLM request failed");
+    }
+    return data;
+  }
+  /**
+   * 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 || '');
+   * }
+   * ```
+   */
+  async *chatStream(messages, options = {}) {
+    const response = await fetch(`${this.baseUrl}/sdk/llm/chat/stream`, {
+      method: "POST",
+      headers: {
+        ...this.headers,
+        "Accept": "text/event-stream"
+      },
+      body: JSON.stringify({
+        messages,
+        model: options.model,
+        provider: options.provider,
+        temperature: options.temperature ?? 0.7,
+        max_tokens: options.max_tokens ?? 1e3
+      })
+    });
+    if (!response.ok) {
+      const errorData = await response.json();
+      if (errorData.code === "PERMISSION_REQUIRED") {
+        throw new LLMPermissionError(errorData.permission || "llm.chat");
+      }
+      throw new LLMProviderError(errorData.error || "Stream request failed");
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new LLMProviderError("Response body is not readable");
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let isErrorEvent = false;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmedLine = line.trim();
+          if (!trimmedLine || trimmedLine.startsWith(":")) continue;
+          if (trimmedLine.startsWith("event: error")) {
+            isErrorEvent = true;
+            continue;
+          }
+          if (trimmedLine.startsWith("data: ")) {
+            const jsonStr = trimmedLine.slice(6);
+            if (jsonStr === "[DONE]") {
+              isErrorEvent = false;
+              continue;
+            }
+            try {
+              const data = JSON.parse(jsonStr);
+              if (isErrorEvent) {
+                isErrorEvent = false;
+                throw new LLMProviderError(
+                  data.error || "Stream error",
+                  data.code || "LLM_STREAM_ERROR"
+                );
+              }
+              const chunk = data;
+              if (chunk.error) {
+                throw new LLMProviderError(
+                  chunk.message || "Stream error"
+                );
+              }
+              yield chunk;
+            } catch (parseError) {
+              isErrorEvent = false;
+              if (jsonStr !== "[DONE]") {
+                console.warn("[LLM Stream] Parse error:", jsonStr);
+              }
+              if (parseError instanceof LLMProviderError) throw parseError;
+            }
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  /**
+   * 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']);
+   * ```
+   */
+  async embed(input, options = {}) {
+    const inputArray = Array.isArray(input) ? input : [input];
+    const response = await fetch(`${this.baseUrl}/sdk/llm/embed`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({
+        input: inputArray,
+        provider: options.provider,
+        model: options.model
+      })
+    });
+    const data = await response.json();
+    if (data.code === "PERMISSION_REQUIRED") {
+      throw new LLMPermissionError(data.permission || "llm.embed");
+    }
+    if (data.code === "PROVIDER_UNAVAILABLE") {
+      throw new LLMProviderError(data.error || "Embedding provider not available");
+    }
+    return data;
+  }
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async embedAndStore(params) {
+    const { texts, documentId, workspaceId, idPrefix = "chunk", provider, model } = params;
+    const embedResult = await this.embed(texts, { provider, model });
+    if (!embedResult.success || !embedResult.embeddings) {
+      return {
+        success: false,
+        error: embedResult.error || "Embedding failed",
+        code: embedResult.code
+      };
+    }
+    const vectors = texts.map((text, i) => ({
+      id: `${idPrefix}_${i}`,
+      vector: embedResult.embeddings[i],
+      metadata: {
+        text,
+        documentId,
+        workspaceId
+      }
+    }));
+    return this.vectors.upsert(vectors, { workspaceId });
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async search(query, options = {}) {
+    const embedResult = await this.embed(query, {
+      provider: options.provider,
+      model: options.model
+    });
+    if (!embedResult.success || !embedResult.embeddings?.[0]) {
+      throw new LLMProviderError("Failed to embed query");
+    }
+    const queryResult = await this.vectors.query(embedResult.embeddings[0], options);
+    if (!queryResult.success) {
+      throw new LLMProviderError(queryResult.error || "Vector search failed");
+    }
+    return queryResult.results || [];
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
@@ -443,6 +821,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName);
     this.task = new TaskModule(this.realtimexUrl, this.appName, this.appId);
     this.port = new PortModule(config.defaultPort);
+    this.llm = new LLMModule(this.realtimexUrl, this.appId);
     if (this.permissions.length > 0) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
@@ -493,10 +872,14 @@ var RealtimeXSDK = _RealtimeXSDK;
 export {
   ActivitiesModule,
   ApiModule,
+  LLMModule,
+  LLMPermissionError,
+  LLMProviderError,
   PermissionDeniedError,
   PermissionRequiredError,
   PortModule,
   RealtimeXSDK,
   TaskModule,
+  VectorStore,
   WebhookModule
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.0.9",
+    "version": "1.1.1",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",