@qelos/sdk 3.11.2 → 3.11.4

package/src/administrator/integrations.ts

@@ -0,0 +1,65 @@
+import { QelosSDKOptions, RequestExtra } from '../types';
+import BaseSDK from '../base-sdk';
+import { IIntegration } from '@qelos/global-types';
+
+export default class QlIntegrations extends BaseSDK {
+  private relativePath = '/api/integrations';
+
+  constructor(private options: QelosSDKOptions) {
+    super(options)
+  }
+
+  getIntegration(integrationId: string, extra?: RequestExtra) {
+    return this.callJsonApi<IIntegration>(`${this.relativePath}/${integrationId}`, extra);
+  }
+
+  getList(query?: { 
+    plugin?: string;
+    user?: string;
+    'trigger.source'?: string;
+    'target.source'?: string;
+    'trigger.kind'?: string;
+    'target.kind'?: string;
+    kind?: string;
+    source?: string;
+    active?: boolean;
+    id?: string;
+    _id?: string;
+  }, extra?: RequestExtra) {
+    return this.callJsonApi<IIntegration[]>(this.relativePath + this.getQueryParams(query), extra);
+  }
+
+  remove(integrationId: string): Promise<any> {
+    return this.callApi(`${this.relativePath}/${integrationId}`, { method: 'delete' });
+  }
+
+  update(integrationId: string, changes: {
+    active?: boolean;
+    trigger?: any;
+    target?: any;
+    dataManipulation?: any;
+  }): Promise<IIntegration> {
+    return this.callJsonApi<IIntegration>(
+      `${this.relativePath}/${integrationId}`,
+      {
+        method: 'put',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(changes)
+      }
+    )
+  }
+
+  create(integration: {
+    trigger: any;
+    target: any;
+    dataManipulation?: any;
+    active?: boolean;
+  }): Promise<IIntegration> {
+    return this.callJsonApi<IIntegration>(this.relativePath, {
+      method: 'post',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(integration)
+    })
+  }
+
+}

package/src/ai/chat.ts

@@ -0,0 +1,187 @@
+import BaseSDK from '../base-sdk';
+import { QelosSDKOptions } from '../types';
+import { 
+  IChatCompletionOptions, 
+  IChatCompletionResponse, 
+  ISSEStreamProcessor 
+} from '../ai';
+
+export default class ChatSDK extends BaseSDK {
+  private relativePath = '/api/ai';
+
+  constructor(options: QelosSDKOptions) {
+    super(options);
+  }
+
+  /**
+   * Create a chat completion without a thread
+   */
+  chat(
+    integrationId: string,
+    options: IChatCompletionOptions
+  ): Promise<IChatCompletionResponse> {
+    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)
+    });
+  }
+
+  /**
+   * Create a chat completion with a thread
+   */
+  chatInThread(
+    integrationId: string,
+    threadId: string,
+    options: IChatCompletionOptions
+  ): Promise<IChatCompletionResponse> {
+    const queryParams = this.getQueryParams(options.queryParams || {});
+    return this.callJsonApi<IChatCompletionResponse>(
+      `${this.relativePath}/${integrationId}/chat-completion/${threadId}${queryParams}`,
+      {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(options)
+      }
+    );
+  }
+
+  /**
+   * Create a streaming chat completion without a thread
+   * Returns a ReadableStream for Server-Sent Events
+   */
+  async stream(
+    integrationId: string,
+    options: IChatCompletionOptions
+  ): Promise<ReadableStream<Uint8Array>> {
+    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',
+        'accept': 'text/event-stream'
+      },
+      body: JSON.stringify({ ...options, stream: true })
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return response.body!;
+  }
+
+  /**
+   * Create a streaming chat completion with a thread
+   * Returns a ReadableStream for Server-Sent Events
+   */
+  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}${queryParams}`,
+      {
+        method: 'POST',
+        headers: { 
+          'content-type': 'application/json',
+          'accept': 'text/event-stream'
+        },
+        body: JSON.stringify({ ...options, stream: true })
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return response.body!;
+  }
+
+  /**
+   * Helper method to parse Server-Sent Events stream
+   */
+  parseSSEStream(stream: ReadableStream<Uint8Array>): ISSEStreamProcessor {
+    const processStream = async (onData: (data: any) => void | boolean): Promise<void> => {
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          buffer += decoder.decode(value, { stream: true });
+          let lines = buffer.split(/\r?\n/);
+          buffer = lines.pop() || ""; // Keep incomplete line
+
+          for (const line of lines) {
+            if (line.startsWith('data: ')) {
+              const data = line.slice(6);
+              if (data === '[DONE]') return;
+              
+              try {
+                const parsed = JSON.parse(data);
+                const shouldContinue = onData(parsed);
+                if (shouldContinue === false) {
+                  return;
+                }
+              } catch (e) {
+                // Skip invalid JSON
+              }
+            }
+          }
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    };
+
+    const processor = {
+      async *[Symbol.asyncIterator]() {
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";        
+        
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+              break;
+            }
+
+            buffer += decoder.decode(value, { stream: true });
+            let lines = buffer.split(/\r?\n/);
+            buffer = lines.pop() || ""; // Keep incomplete line
+
+            for (const line of lines) {
+              if (line.startsWith('data: ')) {
+                const data = line.slice(6);
+                if (data === '[DONE]') {
+                  return;
+                }
+                
+                try {
+                  const parsed = JSON.parse(data);
+                  yield parsed;
+                } catch (e) {
+                  //
+                }
+              }
+            }
+          }
+        } finally {
+          reader.releaseLock();
+        }
+      },
+      
+      processManually: processStream
+    };
+    
+    return processor as ISSEStreamProcessor;
+  }
+}

package/src/ai/index.ts

@@ -0,0 +1,4 @@
+export { default as ThreadsSDK } from './threads';
+export { default as ChatSDK } from './chat';
+export { default as RAGSDK } from './rag';
+export * from './types';

package/src/ai/rag.ts

@@ -0,0 +1,72 @@
+import BaseSDK from '../base-sdk';
+import { QelosSDKOptions } from '../types';
+import { 
+  ICreateVectorStorageRequest, 
+  IUploadContentRequest, 
+  IClearStorageRequest, 
+  IVectorStore 
+} from '../ai';
+
+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)
+    });
+  }
+}

package/src/ai/threads.ts

@@ -0,0 +1,56 @@
+import BaseSDK from '../base-sdk';
+import { QelosSDKOptions } from '../types';
+import { IThread, ICreateThreadRequest } from '../ai';
+
+export default class ThreadsSDK extends BaseSDK {
+  private relativePath = '/api/ai';
+
+  constructor(options: QelosSDKOptions) {
+    super(options);
+  }
+
+  /**
+   * Create a new thread
+   */
+  create(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
+   */
+  getOne(threadId: string): Promise<IThread> {
+    return this.callJsonApi<IThread>(`${this.relativePath}/threads/${threadId}${this.getQueryParams({})}`);
+  }
+
+  /**
+   * List threads with optional filters
+   */
+  list(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
+   */
+  delete(threadId: string): Promise<{ success: boolean }> {
+    return this.callJsonApi<{ success: boolean }>(`${this.relativePath}/threads/${threadId}${this.getQueryParams({})}`, {
+      method: 'DELETE'
+    });
+  }
+}

package/src/ai/types.ts

@@ -0,0 +1,101 @@
+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;
+  queryParams?: Record<string, any>;
+}
+
+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 interface ICreateVectorStorageRequest {
+  integrationId: string;
+  scope: 'thread' | 'user' | 'workspace' | 'tenant';
+  subjectId?: string;
+  expirationAfterDays?: number;
+}
+
+export interface IUploadContentRequest {
+  integrationId?: string;
+  vectorStoreId?: string;
+  content: string | object;
+  fileName?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface IClearStorageRequest {
+  integrationId?: string;
+  vectorStoreId?: string;
+  fileIds?: string[];
+}
+
+export interface IVectorStore {
+  _id: string;
+  scope: string;
+  subjectId?: string;
+  tenant: string;
+  agent: string;
+  externalId: string;
+  expirationAfterDays?: number;
+  created: Date;
+}

package/src/ai-sdk-migration-guide.md

@@ -0,0 +1,172 @@
+# Qelos AI SDK Migration Guide
+
+The Qelos AI SDK has been refactored to provide a more organized and intuitive API with three sub-SDKs:
+- `threads` - Thread CRUD operations
+- `chat` - Chat completion (streaming and non-streaming) and SSE parsing
+- `rag` - Vector storage management for RAG (Retrieval-Augmented Generation)
+
+## File Structure
+
+The SDK is now split into multiple files for better organization:
+```
+/packages/sdk/src/ai/
+├── index.ts      - Exports all sub-SDKs and types
+├── types.ts      - All AI-related type definitions
+├── threads.ts    - ThreadsSDK implementation
+├── chat.ts       - ChatSDK implementation
+└── rag.ts        - RAGSDK implementation
+```
+
+## New API Structure
+
+### 1. Threads Sub-SDK
+
+All thread-related operations are now available under `sdk.ai.threads`:
+
+```typescript
+// Create a new thread
+const thread = await sdk.ai.threads.create({
+  integration: 'integration-id',
+  title: 'Optional title'
+});
+
+// Get a specific thread
+const thread = 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');
+```
+
+### 2. Chat Sub-SDK
+
+All chat completion operations are now available under `sdk.ai.chat`:
+
+```typescript
+// Non-streaming chat
+const response = await sdk.ai.chat.chat('integration-id', {
+  messages: [{ role: 'user', content: 'Hello!' }],
+  model: 'gpt-4',
+  queryParams: { bypassAdmin: true } // Optional query parameters
+});
+
+// Non-streaming chat in thread
+const response = await sdk.ai.chat.chatInThread('integration-id', 'thread-id', {
+  messages: [{ role: 'user', content: 'Hello!' }]
+});
+
+// Streaming chat
+const stream = await sdk.ai.chat.stream('integration-id', {
+  messages: [{ role: 'user', content: 'Hello!' }],
+  stream: true
+});
+
+// Streaming chat in thread
+const stream = await sdk.ai.chat.streamInThread('integration-id', 'thread-id', {
+  messages: [{ role: 'user', content: 'Hello!' }],
+  stream: true
+});
+
+// Parse SSE stream
+const processor = sdk.ai.chat.parseSSEStream(stream);
+for await (const chunk of processor) {
+  console.log(chunk);
+}
+```
+
+### 3. RAG Sub-SDK
+
+All vector storage operations are now available under `sdk.ai.rag`:
+
+```typescript
+// Create vector storage
+const result = await sdk.ai.rag.createStorage('source-id', {
+  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('source-id', {
+  integrationId: 'integration-id',
+  content: 'Your content here', // Can be string or object
+  fileName: 'document.txt',
+  metadata: { type: 'documentation' }
+});
+
+// Clear files from storage
+const clearResult = await sdk.ai.rag.clearStorage('source-id', {
+  integrationId: 'integration-id',
+  fileIds: ['file-id-1', 'file-id-2'] // Optional: clears all if not provided
+});
+
+// Get vector stores (internal API)
+const stores = await sdk.ai.rag.getVectorStores({
+  scope: 'thread',
+  subjectId: 'thread-id'
+});
+
+// Internal API methods (for server-side use)
+await sdk.ai.rag.uploadContentInternal('source-id', data);
+await sdk.ai.rag.clearStorageInternal('source-id', data);
+```
+
+## Backward Compatibility
+
+The old API methods are still available and marked as deprecated. They internally delegate to the new sub-SDKs:
+
+```typescript
+// These still work but are deprecated:
+await sdk.ai.createThread(data); // → sdk.ai.threads.create(data)
+await sdk.ai.getThread(id); // → sdk.ai.threads.getOne(id)
+await sdk.ai.streamChat(id, options); // → sdk.ai.chat.stream(id, options)
+await sdk.ai.parseSSEStream(stream); // → sdk.ai.chat.parseSSEStream(stream)
+```
+
+## Migration Benefits
+
+1. **Better Organization**: Related functionality is grouped together
+2. **Improved Discoverability**: IDE autocomplete shows relevant methods for each sub-SDK
+3. **Type Safety**: Better TypeScript support with specific interfaces for each sub-domain
+4. **Future-Proof**: Easy to extend each sub-SDK independently
+
+## Updating Your Code
+
+While the old API still works, we recommend updating to the new structure:
+
+```typescript
+// Old way
+const thread = await sdk.ai.createThread({ integration: 'id' });
+const stream = await sdk.ai.streamChat('id', options);
+for await (const chunk of sdk.ai.parseSSEStream(stream)) {
+  // process chunk
+}
+
+// New way
+const thread = await sdk.ai.threads.create({ integration: 'id' });
+const stream = await sdk.ai.chat.stream('id', options);
+for await (const chunk of sdk.ai.chat.parseSSEStream(stream)) {
+  // process chunk
+}
+```
+
+## Query Parameters
+
+The `IChatCompletionOptions` interface now includes an optional `queryParams` field for passing additional query parameters:
+
+```typescript
+await sdk.ai.chat.stream('integration-id', {
+  messages: [{ role: 'user', content: 'Hello!' }],
+  queryParams: {
+    bypassAdmin: true,
+    customParam: 'value'
+  }
+});
+```