@memberjunction/ai 2.44.0 → 2.46.0

package/dist/generic/chat.types.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { BaseParams, BaseResult, ModelUsage } from "./baseModel";
 export declare const ChatMessageRole: {
     readonly system: "system";
@@ -35,6 +36,7 @@ export declare class ChatParams extends BaseParams {
     effortLevel?: string;
     enableCaching?: boolean;
     includeLogProbs?: boolean;
+    cancellationToken?: AbortSignal;
 }
 export declare function GetUserMessageFromChatParams(p: ChatParams): ChatMessageContent | undefined;
 export declare function GetSystemPromptFromChatParams(p: ChatParams): ChatMessageContent | undefined;

package/dist/generic/chat.types.d.ts.map

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

package/dist/generic/chat.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"chat.types.js","sourceRoot":"","sources":["../../src/generic/chat.types.ts"],"names":[],"mappings":";;;AAAA,2CAAgE;AAOnD,QAAA,eAAe,GAAG;IAC3B,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,WAAW;CAChB,CAAC;AA0GX,MAAa,UAAW,SAAQ,sBAAU;IAA1C;;QAII,aAAQ,GAAkB,EAAE,CAAC;QAO7B,cAAS,GAAa,KAAK,CAAC;QAsB5B,kBAAa,GAAa,IAAI,CAAC;QAQ/B,oBAAe,GAAa,KAAK,CAAC;IACtC,CAAC;CAAA;AA1CD,gCA0CC;AAMD,SAAgB,4BAA4B,CAAC,CAAa;IACtD,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,uBAAe,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;AAC1E,CAAC;AAFD,oEAEC;AAMD,SAAgB,6BAA6B,CAAC,CAAa;IACvD,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,uBAAe,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;AAC5E,CAAC;AAFD,sEAEC;AAqGD,MAAa,UAAW,SAAQ,sBAAU;CASzC;AATD,gCASC"}
+{"version":3,"file":"chat.types.js","sourceRoot":"","sources":["../../src/generic/chat.types.ts"],"names":[],"mappings":";;;AAAA,2CAAgE;AAOnD,QAAA,eAAe,GAAG;IAC3B,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,WAAW;CAChB,CAAC;AA0GX,MAAa,UAAW,SAAQ,sBAAU;IAA1C;;QAII,aAAQ,GAAkB,EAAE,CAAC;QAO7B,cAAS,GAAa,KAAK,CAAC;QAsB5B,kBAAa,GAAa,IAAI,CAAC;QAQ/B,oBAAe,GAAa,KAAK,CAAC;IAQtC,CAAC;CAAA;AAjDD,gCAiDC;AAMD,SAAgB,4BAA4B,CAAC,CAAa;IACtD,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,uBAAe,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;AAC1E,CAAC;AAFD,oEAEC;AAMD,SAAgB,6BAA6B,CAAC,CAAa;IACvD,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,uBAAe,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;AAC5E,CAAC;AAFD,sEAEC;AAqGD,MAAa,UAAW,SAAQ,sBAAU;CASzC;AATD,gCASC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ai",
-  "version": "2.44.0",
+  "version": "2.46.0",
   "description": "MemberJunction: AI Module - LLMs and other AI services wrapped and abstracted for use in MemberJunction",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,7 +15,7 @@
   "author": "MemberJunction.com",
   "license": "ISC",
   "dependencies": {
-    "@memberjunction/global": "2.44.0",
+    "@memberjunction/global": "2.46.0",
     "dotenv": "^16.4.1",
     "rxjs": "^7.8.1",
     "typeorm": "^0.3.20"

package/readme.md

@@ -241,6 +241,187 @@ const params: ChatParams = {
 await llm.ChatCompletion(params);
 ```
 
+### Cancellable Operations with AbortSignal
+
+The MemberJunction AI Core package supports cancellation of long-running operations using the standard JavaScript `AbortSignal` pattern. This provides a clean, standardized way to cancel AI operations when needed.
+
+#### Understanding the AbortSignal Pattern
+
+The `AbortSignal` pattern uses a **separation of concerns** approach:
+
+- **Controller (Caller)**: Creates the `AbortController` and decides **when** to cancel
+- **Worker (AI Operations)**: Receives the `AbortSignal` token and handles **how** to cancel
+
+#### Basic Cancellation Example
+
+```typescript
+import { ChatParams, BaseLLM } from '@memberjunction/ai';
+
+async function cancellableAIChat() {
+  // Create the cancellation controller (the "boss")
+  const controller = new AbortController();
+  
+  // Set up automatic timeout cancellation
+  const timeout = setTimeout(() => {
+    controller.abort(); // Cancel after 30 seconds
+  }, 30000);
+
+  try {
+    const params: ChatParams = {
+      model: 'gpt-4',
+      messages: [
+        { role: 'user', content: 'Write a very long story...' }
+      ],
+      cancellationToken: controller.signal // Pass the signal token
+    };
+
+    const result = await llm.ChatCompletion(params);
+    clearTimeout(timeout); // Clear timeout if completed successfully
+    return result;
+    
+  } catch (error) {
+    if (error.message.includes('cancelled')) {
+      console.log('Operation was cancelled');
+    } else {
+      console.error('Operation failed:', error);
+    }
+  }
+}
+```
+
+#### User-Initiated Cancellation
+
+Perfect for UI applications where users can cancel operations:
+
+```typescript
+class AIInterface {
+  private currentController: AbortController | null = null;
+
+  async startAIConversation() {
+    // Create new controller for this conversation
+    this.currentController = new AbortController();
+    
+    try {
+      const result = await llm.ChatCompletion({
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'Generate a detailed report...' }],
+        cancellationToken: this.currentController.signal
+      });
+      
+      console.log('AI Response:', result.data.choices[0].message.content);
+    } catch (error) {
+      if (error.message.includes('cancelled')) {
+        console.log('User cancelled the conversation');
+      }
+    } finally {
+      this.currentController = null;
+    }
+  }
+
+  // Called when user clicks "Cancel" button
+  cancelConversation() {
+    if (this.currentController) {
+      this.currentController.abort(); // Instant cancellation
+    }
+  }
+}
+```
+
+#### Multiple Cancellation Sources
+
+One signal can be cancelled from multiple sources:
+
+```typescript
+async function smartAIExecution() {
+  const controller = new AbortController();
+  const signal = controller.signal;
+
+  // 1. User cancel button
+  document.getElementById('cancel')?.addEventListener('click', () => {
+    controller.abort(); // User cancellation
+  });
+
+  // 2. Resource limit cancellation  
+  if (await checkMemoryUsage() > MAX_MEMORY) {
+    controller.abort(); // Resource limit cancellation
+  }
+
+  // 3. Window unload cancellation
+  window.addEventListener('beforeunload', () => {
+    controller.abort(); // Page closing cancellation
+  });
+
+  // 4. Timeout cancellation
+  setTimeout(() => controller.abort(), 60000); // 1 minute timeout
+
+  try {
+    const result = await llm.ChatCompletion({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: 'Complex analysis task...' }],
+      cancellationToken: signal // One token, many cancel sources!
+    });
+    
+    return result;
+  } catch (error) {
+    // The AI operation doesn't know WHY it was cancelled - just that it should stop
+    console.log('AI operation was cancelled:', error.message);
+  }
+}
+```
+
+#### How It Works Internally
+
+The AI Core package implements cancellation at multiple levels:
+
+1. **BaseLLM Level**: Checks cancellation token before and during operations
+2. **Provider Level**: Native cancellation support where available (e.g., fetch API)
+3. **Fallback Pattern**: Promise.race for providers without native cancellation
+
+```typescript
+// Internal implementation example (simplified)
+async ChatCompletion(params: ChatParams): Promise<ChatResult> {
+  // Check if already cancelled before starting
+  if (params.cancellationToken?.aborted) {
+    throw new Error('Operation was cancelled');
+  }
+
+  // For providers with native cancellation support
+  if (this.hasNativeCancellation) {
+    return await this.callProviderAPI({
+      ...params,
+      signal: params.cancellationToken // Native fetch cancellation
+    });
+  }
+
+  // Fallback: Promise.race pattern for other providers
+  const promises = [
+    this.callProviderAPI(params) // The actual AI call
+  ];
+
+  if (params.cancellationToken) {
+    promises.push(
+      new Promise<never>((_, reject) => {
+        params.cancellationToken!.addEventListener('abort', () => {
+          reject(new Error('Operation was cancelled'));
+        });
+      })
+    );
+  }
+
+  return await Promise.race(promises);
+}
+```
+
+#### Key Benefits
+
+1. **🎯 Responsive UX**: Users can cancel long-running AI operations instantly
+2. **💾 Resource Management**: Prevent runaway operations from consuming resources  
+3. **🔄 Composable**: Easy to combine user actions, timeouts, and resource limits
+4. **📱 Standard API**: Uses native JavaScript AbortSignal - no custom patterns
+5. **🧹 Clean Cleanup**: Automatic resource cleanup when operations are cancelled
+
+The cancellation token pattern provides a **robust, standardized way** to make AI operations responsive and resource-efficient!
+
 ### Text Summarization
 
 For summarizing longer text content: