@qelos/sdk 3.11.3 → 3.11.5

package/examples/ai-sdk-usage.ts

@@ -0,0 +1,170 @@
+// Example usage of the new Qelos AI SDK with sub-SDKs
+
+import QelosSDK from '../src';
+// Alternatively, you can import specific sub-SDKs:
+// import { ThreadsSDK, ChatSDK, RAGSDK } from '../src/ai';
+
+// Initialize the SDK
+const sdk = new QelosSDK({
+  appUrl: 'https://your-qelos-instance.com',
+  fetch: globalThis.fetch || require('node-fetch'),
+  accessToken: 'your-access-token'
+});
+
+// ===== THREADS SUB-SDK =====
+async function threadExamples() {
+  // Create a new thread
+  const thread = await sdk.ai.threads.create({
+    integration: 'integration-id',
+    title: 'Customer Support Chat'
+  });
+  
+  // Get a specific thread
+  const retrievedThread = await sdk.ai.threads.getOne(thread._id!);
+  
+  // List threads with filters
+  const threads = await sdk.ai.threads.list({
+    integration: 'integration-id',
+    limit: 10,
+    page: 1
+  });
+  
+  // Delete a thread
+  await sdk.ai.threads.delete(thread._id!);
+}
+
+// ===== CHAT SUB-SDK =====
+async function chatExamples() {
+  const integrationId = 'your-integration-id';
+  const messages = [
+    { role: 'user', content: 'Hello, how can you help me?' }
+  ];
+  
+  // Non-streaming chat
+  const response = await sdk.ai.chat.chat(integrationId, {
+    messages,
+    model: 'gpt-4',
+    temperature: 0.7,
+    queryParams: { bypassAdmin: true } // Optional query params
+  });
+  
+  console.log(response.choices[0].message.content);
+  
+  // Streaming chat
+  const stream = await sdk.ai.chat.stream(integrationId, {
+    messages,
+    stream: true
+  });
+  
+  // Parse the SSE stream
+  const processor = sdk.ai.chat.parseSSEStream(stream);
+  for await (const chunk of processor) {
+    if (chunk.choices?.[0]?.delta?.content) {
+      console.log(chunk.choices[0].delta.content);
+    }
+  }
+  
+  // Chat in a thread
+  const threadId = 'thread-id';
+  const threadResponse = await sdk.ai.chat.chatInThread(integrationId, threadId, {
+    messages
+  });
+  
+  // Streaming chat in a thread
+  const threadStream = await sdk.ai.chat.streamInThread(integrationId, threadId, {
+    messages,
+    stream: true
+  });
+  
+  for await (const chunk of sdk.ai.chat.parseSSEStream(threadStream)) {
+    console.log(chunk);
+  }
+}
+
+// ===== RAG SUB-SDK =====
+async function ragExamples() {
+  const sourceId = 'your-ai-source-id';
+  
+  // Create vector storage
+  const storage = await sdk.ai.rag.createStorage(sourceId, {
+    integrationId: 'integration-id',
+    scope: 'thread', // 'thread' | 'user' | 'workspace' | 'tenant'
+    subjectId: 'thread-id', // Required for non-tenant scopes
+    expirationAfterDays: 30
+  });
+  
+  // Upload content to storage
+  const uploadResult = await sdk.ai.rag.uploadContent(sourceId, {
+    integrationId: 'integration-id',
+    content: 'This is the content to be indexed for RAG.',
+    fileName: 'document.txt',
+    metadata: { type: 'documentation', category: 'help' }
+  });
+  
+  // Upload JSON content
+  const jsonUpload = await sdk.ai.rag.uploadContent(sourceId, {
+    integrationId: 'integration-id',
+    content: { title: 'Product Info', description: '...' },
+    fileName: 'product-info.json'
+  });
+  
+  // Clear specific files
+  const clearResult = await sdk.ai.rag.clearStorage(sourceId, {
+    integrationId: 'integration-id',
+    fileIds: [uploadResult.fileId]
+  });
+  
+  // Clear all files (if no fileIds provided)
+  await sdk.ai.rag.clearStorage(sourceId, {
+    integrationId: 'integrationId'
+  });
+  
+  // Get vector stores (internal API - server-side only)
+  const stores = await sdk.ai.rag.getVectorStores({
+    scope: 'thread',
+    subjectId: 'thread-id'
+  });
+}
+
+// ===== COMBINED EXAMPLE =====
+async function combinedExample() {
+  // 1. Create a thread
+  const thread = await sdk.ai.threads.create({
+    integration: 'integration-id',
+    title: 'RAG-enabled Chat'
+  });
+  
+  // 2. Upload knowledge base content
+  await sdk.ai.rag.uploadContent('source-id', {
+    integrationId: 'integration-id',
+    content: 'Your knowledge base content here...',
+    fileName: 'knowledge-base.txt'
+  });
+  
+  // 3. Chat with RAG
+  const stream = await sdk.ai.chat.streamInThread(
+    'integration-id',
+    thread._id!,
+    {
+      messages: [
+        { role: 'user', content: 'What do you know about the topic?' }
+      ],
+      stream: true
+    }
+  );
+  
+  // 4. Process the response
+  for await (const chunk of sdk.ai.chat.parseSSEStream(stream)) {
+    if (chunk.choices?.[0]?.delta?.content) {
+      console.log(chunk.choices[0].delta.content);
+    }
+  }
+}
+
+// Export for reference
+export {
+  threadExamples,
+  chatExamples,
+  ragExamples,
+  combinedExample
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qelos/sdk",
-  "version": "3.11.3",
+  "version": "3.11.5",
   "description": "SDK for Qelos API",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,6 +12,9 @@
       "administrator/*": [
         "./dist/administrator/*.d.ts"
       ],
+      "ai/*": [
+        "./dist/ai/*.d.ts"
+      ],
       "workspaces": [
         "./dist/workspaces.d.ts"
       ],
@@ -45,6 +48,18 @@
       "require": "./dist/administrator/*.js",
       "default": "./dist/administrator/*.js"
     },
+    "./ai": {
+      "types": "./dist/ai/index.d.ts",
+      "import": "./dist/ai/index.js",
+      "require": "./dist/ai/index.js",
+      "default": "./dist/ai/index.js"
+    },
+    "./ai/*": {
+      "types": "./dist/ai/*.d.ts",
+      "import": "./dist/ai/*.js",
+      "require": "./dist/ai/*.js",
+      "default": "./dist/ai/*.js"
+    },
     "./workspaces": {
       "types": "./dist/workspaces.d.ts",
       "import": "./dist/workspaces.js",
@@ -87,10 +102,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@qelos/global-types": "^3.9.0"
+    "@qelos/global-types": "^3.11.4"
   },
   "devDependencies": {
-    "tsx": "^4.20.4",
+    "tsx": "^4.21.0",
     "typescript": "^4.9.5"
   },
   "gitHead": "13468bc51557291935b96b1aeaa837b8b52861e8",

package/src/{ai.ts → ai/chat.ts}

@@ -1,130 +1,18 @@
-import { QelosSDKOptions } from './types';
-import BaseSDK from './base-sdk';
-
-export interface IMessage {
-  role: string;
-  content: string;
-  timestamp?: Date | string;
-  tool_calls?: any[];
-  name?: string;
-  tool_call_id?: string;
-  function_call?: any;
-  message_id?: string;
-}
-
-export interface IMessageSummary {
-  fromIndex: number;
-  toIndex: number;
-  summary: string;
-}
-
-export interface IThread {
-  _id?: string;
-  integration: string;
-  title?: string;
-  messages: IMessage[];
-  messageSummaries: IMessageSummary[];
-  created?: Date;
-  updated?: Date;
-  user?: string;
-  workspace?: string;
-}
-
-export interface IChatCompletionOptions {
-  messages: IMessage[];
-  model?: string;
-  temperature?: number;
-  top_p?: number;
-  frequency_penalty?: number;
-  presence_penalty?: number;
-  stop?: string | string[];
-  max_tokens?: number;
-  response_format?: any;
-  context?: Record<string, any>;
-  stream?: boolean;
-}
-
-export interface ISSEStreamProcessor extends AsyncIterable<any> {
-  processManually(onData: (data: any) => void | boolean): Promise<void>;
-}
-
-export interface IChatCompletionResponse {
-  id: string;
-  object: string;
-  created: number;
-  model: string;
-  choices: Array<{
-    index: number;
-    message: IMessage;
-    finish_reason: string;
-  }>;
-  usage?: {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-  };
-}
-
-export interface ICreateThreadRequest {
-  integration: string;
-  title?: string;
-}
-
-export default class QlAI extends BaseSDK {
+import BaseSDK from '../base-sdk';
+import { QelosSDKOptions } from '../types';
+import { 
+  IChatCompletionOptions, 
+  IChatCompletionResponse, 
+  ISSEStreamProcessor 
+} from '.';
+
+export default class ChatSDK extends BaseSDK {
   private relativePath = '/api/ai';
+
   constructor(options: QelosSDKOptions) {
     super(options);
   }
 
-  // Thread CRUD Operations
-
-  /**
-   * Create a new thread
-   */
-  createThread(data: ICreateThreadRequest): Promise<IThread> {
-    return this.callJsonApi<IThread>(this.relativePath + '/threads', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(data)
-    });
-  }
-
-  /**
-   * Get a specific thread by ID
-   */
-  getThread(threadId: string): Promise<IThread> {
-    return this.callJsonApi<IThread>(`${this.relativePath}/threads/${threadId}${this.getQueryParams({})}`);
-  }
-
-  /**
-   * List threads with optional filters
-   */
-  listThreads(options?: {
-    integration?: string;
-    limit?: number;
-    page?: number;
-    sort?: string;
-    user?: string;
-    workspace?: string;
-    [key: string]: string | number;
-  }): Promise<IThread[]> {
-    const queryParams = this.getQueryParams(options);
-    return this.callJsonApi<IThread[]>(
-      `${this.relativePath}/threads${queryParams}`
-    );
-  }
-
-  /**
-   * Delete a thread
-   */
-  deleteThread(threadId: string): Promise<{ success: boolean }> {
-    return this.callJsonApi<{ success: boolean }>(`${this.relativePath}/threads/${threadId}${this.getQueryParams({})}`, {
-      method: 'DELETE'
-    });
-  }
-
-  // Chat Completion Operations
-
   /**
    * Create a chat completion without a thread
    */
@@ -132,7 +20,8 @@ export default class QlAI extends BaseSDK {
     integrationId: string,
     options: IChatCompletionOptions
   ): Promise<IChatCompletionResponse> {
-    return this.callJsonApi<IChatCompletionResponse>(`${this.relativePath}/${integrationId}/chat-completion${this.getQueryParams({})}`, {
+    const queryParams = this.getQueryParams(options.queryParams || {});
+    return this.callJsonApi<IChatCompletionResponse>(`${this.relativePath}/${integrationId}/chat-completion${queryParams}`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(options)
@@ -147,8 +36,9 @@ export default class QlAI extends BaseSDK {
     threadId: string,
     options: IChatCompletionOptions
   ): Promise<IChatCompletionResponse> {
+    const queryParams = this.getQueryParams(options.queryParams || {});
     return this.callJsonApi<IChatCompletionResponse>(
-      `${this.relativePath}/${integrationId}/chat-completion/${threadId}${this.getQueryParams({})}`,
+      `${this.relativePath}/${integrationId}/chat-completion/${threadId}${queryParams}`,
       {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
@@ -161,11 +51,12 @@ export default class QlAI extends BaseSDK {
    * Create a streaming chat completion without a thread
    * Returns a ReadableStream for Server-Sent Events
    */
-  async streamChat(
+  async stream(
     integrationId: string,
     options: IChatCompletionOptions
   ): Promise<ReadableStream<Uint8Array>> {
-    const response = await this.callApi(`${this.relativePath}/${integrationId}/chat-completion${this.getQueryParams({ stream: true })}`, {
+    const queryParams = this.getQueryParams({ ...options.queryParams, stream: true });
+    const response = await this.callApi(`${this.relativePath}/${integrationId}/chat-completion${queryParams}`, {
       method: 'POST',
       headers: { 
         'content-type': 'application/json',
@@ -185,13 +76,14 @@ export default class QlAI extends BaseSDK {
    * Create a streaming chat completion with a thread
    * Returns a ReadableStream for Server-Sent Events
    */
-  async streamChatInThread(
+  async streamInThread(
     integrationId: string,
     threadId: string,
     options: IChatCompletionOptions
   ): Promise<ReadableStream<Uint8Array>> {
+    const queryParams = this.getQueryParams({ ...options.queryParams, stream: true });
     const response = await this.callApi(
-      `${this.relativePath}/${integrationId}/chat-completion/${threadId}${this.getQueryParams({ stream: true })}`,
+      `${this.relativePath}/${integrationId}/chat-completion/${threadId}${queryParams}`,
       {
         method: 'POST',
         headers: { 

package/src/ai/index.ts

@@ -0,0 +1,181 @@
+import { QelosSDKOptions } from '../types';
+import BaseSDK from '../base-sdk';
+import ThreadsSDK from './threads';
+import ChatSDK from './chat';
+import RagSDK from './rag';
+import {
+  IMessage,
+  IMessageSummary,
+  IThread,
+  IChatCompletionOptions,
+  ISSEStreamProcessor,
+  IChatCompletionResponse,
+  ICreateThreadRequest,
+  ICreateVectorStorageRequest,
+  IUploadContentRequest,
+  IClearStorageRequest,
+  IVectorStore
+} from './types';
+
+export * from './types';
+
+// Re-export types for backward compatibility
+export {
+  IMessage,
+  IMessageSummary,
+  IThread,
+  IChatCompletionOptions,
+  ISSEStreamProcessor,
+  IChatCompletionResponse,
+  ICreateThreadRequest,
+  ICreateVectorStorageRequest,
+  IUploadContentRequest,
+  IClearStorageRequest,
+  IVectorStore
+};
+
+/**
+ * Qelos AI SDK - Main SDK class with three sub-SDKs
+ * 
+ * This class provides access to AI functionality through three sub-SDKs:
+ * - `threads`: Thread CRUD operations for managing conversation threads
+ * - `chat`: Chat completion operations (streaming and non-streaming)
+ * - `rag`: Vector storage management for Retrieval-Augmented Generation
+ * 
+ * @example
+ * ```typescript
+ * const sdk = new QelosSDK({
+ *   appUrl: 'https://your-qelos-instance.com',
+ *   fetch: globalThis.fetch,
+ *   accessToken: 'your-token'
+ * });
+ * 
+ * // Create a thread
+ * const thread = await sdk.ai.threads.create({ integration: 'id' });
+ * 
+ * // Stream chat
+ * const stream = await sdk.ai.chat.stream('id', { messages: [...] });
+ * for await (const chunk of sdk.ai.chat.parseSSEStream(stream)) {
+ *   console.log(chunk);
+ * }
+ * 
+ * // Upload RAG content
+ * await sdk.ai.rag.uploadContent('sourceId', { content: '...' });
+ * ```
+ */
+// Main AI SDK with sub-SDKs
+export default class QlAI extends BaseSDK {
+  /**
+   * Threads sub-SDK for managing conversation threads
+   */
+  public threads: ThreadsSDK;
+  
+  /**
+   * Chat sub-SDK for chat completion operations
+   */
+  public chat: ChatSDK;
+  
+  /**
+   * RAG sub-SDK for vector storage management
+   */
+  public rag: RagSDK;
+
+  /**
+   * Initialize the AI SDK with sub-SDKs
+   * 
+   * @param options - SDK configuration options
+   */
+  constructor(options: QelosSDKOptions) {
+    super(options);
+    this.threads = new ThreadsSDK(options);
+    this.chat = new ChatSDK(options);
+    this.rag = new RagSDK(options);
+  }
+
+  // Legacy methods for backward compatibility
+  
+  /**
+   * @deprecated Use sdk.threads.create() instead
+   */
+  createThread(data: ICreateThreadRequest): Promise<IThread> {
+    return this.threads.create(data);
+  }
+
+  /**
+   * @deprecated Use sdk.threads.getOne() instead
+   */
+  getThread(threadId: string): Promise<IThread> {
+    return this.threads.getOne(threadId);
+  }
+
+  /**
+   * @deprecated Use sdk.threads.list() instead
+   */
+  listThreads(options?: {
+    integration?: string;
+    limit?: number;
+    page?: number;
+    sort?: string;
+    user?: string;
+    workspace?: string;
+    [key: string]: string | number;
+  }): Promise<IThread[]> {
+    return this.threads.list(options);
+  }
+
+  /**
+   * @deprecated Use sdk.threads.delete() instead
+   */
+  deleteThread(threadId: string): Promise<{ success: boolean }> {
+    return this.threads.delete(threadId);
+  }
+
+  /**
+   * @deprecated Use sdk.chat.chat() instead
+   */
+  chatCompletion(
+    integrationId: string,
+    options: IChatCompletionOptions
+  ): Promise<IChatCompletionResponse> {
+    return this.chat.chat(integrationId, options);
+  }
+
+  /**
+   * @deprecated Use sdk.chat.chatInThread() instead
+   */
+  chatCompletionInThread(
+    integrationId: string,
+    threadId: string,
+    options: IChatCompletionOptions
+  ): Promise<IChatCompletionResponse> {
+    return this.chat.chatInThread(integrationId, threadId, options);
+  }
+
+  /**
+   * @deprecated Use sdk.chat.stream() instead
+   */
+  async streamChat(
+    integrationId: string,
+    options: IChatCompletionOptions
+  ): Promise<ReadableStream<Uint8Array>> {
+    return this.chat.stream(integrationId, options);
+  }
+
+  /**
+   * @deprecated Use sdk.chat.streamInThread() instead
+   */
+  async streamChatInThread(
+    integrationId: string,
+    threadId: string,
+    options: IChatCompletionOptions
+  ): Promise<ReadableStream<Uint8Array>> {
+    return this.chat.streamInThread(integrationId, threadId, options);
+  }
+
+  /**
+   * @deprecated Use sdk.chat.parseSSEStream() instead
+   */
+  parseSSEStream(stream: ReadableStream<Uint8Array>): ISSEStreamProcessor {
+    return this.chat.parseSSEStream(stream);
+  }
+}

package/src/ai/rag.ts

@@ -0,0 +1,72 @@
+import BaseSDK from '../base-sdk';
+import { QelosSDKOptions } from '../types';
+import { 
+  ICreateVectorStorageRequest, 
+  IUploadContentRequest, 
+  IClearStorageRequest, 
+  IVectorStore 
+} from '.';
+
+export default class RagSDK extends BaseSDK {
+  private relativePath = '/api/ai';
+
+  constructor(options: QelosSDKOptions) {
+    super(options);
+  }
+
+  /**
+   * Create a vector storage for RAG
+   */
+  createStorage(
+    sourceId: string,
+    data: ICreateVectorStorageRequest
+  ): Promise<{
+    success: boolean;
+    message: string;
+    vectorStore: IVectorStore;
+  }> {
+    return this.callJsonApi<any>(`${this.relativePath}/sources/${sourceId}/storage${this.getQueryParams({})}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(data)
+    });
+  }
+
+  /**
+   * Upload content to vector storage
+   */
+  uploadContent(
+    sourceId: string,
+    data: IUploadContentRequest
+  ): Promise<{
+    success: boolean;
+    message: string;
+    fileId: string;
+    vectorStoreId: string;
+  }> {
+    return this.callJsonApi<any>(`${this.relativePath}/sources/${sourceId}/storage/upload${this.getQueryParams({})}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(data)
+    });
+  }
+
+  /**
+   * Clear files from vector storage
+   */
+  clearStorage(
+    sourceId: string,
+    data: IClearStorageRequest
+  ): Promise<{
+    success: boolean;
+    message: string;
+    clearedCount: number;
+    vectorStoreId: string;
+  }> {
+    return this.callJsonApi<any>(`${this.relativePath}/sources/${sourceId}/storage/clear${this.getQueryParams({})}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(data)
+    });
+  }
+}