@qelos/sdk 3.11.3 → 3.11.5

package/src/ai/threads.ts

@@ -0,0 +1,56 @@
+import BaseSDK from '../base-sdk';
+import { QelosSDKOptions } from '../types';
+import { IThread, ICreateThreadRequest } from '.';
+
+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'
+  }
+});
+```

package/dist/ai.d.ts

@@ -1,116 +0,0 @@
-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 {
-    private relativePath;
-    constructor(options: QelosSDKOptions);
-    /**
-     * Create a new thread
-     */
-    createThread(data: ICreateThreadRequest): Promise<IThread>;
-    /**
-     * Get a specific thread by ID
-     */
-    getThread(threadId: string): Promise<IThread>;
-    /**
-     * 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[]>;
-    /**
-     * Delete a thread
-     */
-    deleteThread(threadId: string): Promise<{
-        success: boolean;
-    }>;
-    /**
-     * Create a chat completion without a thread
-     */
-    chat(integrationId: string, options: IChatCompletionOptions): Promise<IChatCompletionResponse>;
-    /**
-     * Create a chat completion with a thread
-     */
-    chatInThread(integrationId: string, threadId: string, options: IChatCompletionOptions): Promise<IChatCompletionResponse>;
-    /**
-     * Create a streaming chat completion without a thread
-     * Returns a ReadableStream for Server-Sent Events
-     */
-    streamChat(integrationId: string, options: IChatCompletionOptions): Promise<ReadableStream<Uint8Array>>;
-    /**
-     * Create a streaming chat completion with a thread
-     * Returns a ReadableStream for Server-Sent Events
-     */
-    streamChatInThread(integrationId: string, threadId: string, options: IChatCompletionOptions): Promise<ReadableStream<Uint8Array>>;
-    /**
-     * Helper method to parse Server-Sent Events stream
-     */
-    parseSSEStream(stream: ReadableStream<Uint8Array>): ISSEStreamProcessor;
-}

package/dist/ai.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ai.js","sourceRoot":"","sources":["../src/ai.ts"],"names":[],"mappings":"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"}