@n8n/ai-utilities 0.2.0

package/LICENSE.md

@@ -0,0 +1,88 @@
+# License
+
+Portions of this software are licensed as follows:
+
+- Content of branches other than the main branch (i.e. "master") are not licensed.
+- Source code files that contain ".ee." in their filename or ".ee" in their dirname are NOT licensed under
+  the Sustainable Use License.
+  To use source code files that contain ".ee." in their filename or ".ee" in their dirname you must hold a
+	valid n8n Enterprise License specifically allowing you access to such source code files and as defined
+	in "LICENSE_EE.md".
+- All third party components incorporated into the n8n Software are licensed under the original license
+  provided by the owner of the applicable component.
+- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use
+  License" as defined below.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The “licensor” is the entity offering these terms.
+
+The “software” is the software the licensor makes available under these terms, including any portion of it.
+
+“You” refers to the individual or entity agreeing to these terms.
+
+“Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+“Your license” is the license granted to you for the software under these terms.
+
+“Use” means anything you do with the software requiring your license.
+
+“Trademark” means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,468 @@
+# @n8n/ai-utilities
+
+Utilities for building AI nodes in n8n.
+
+## Installation
+
+This package is part of the n8n monorepo and should be installed via the workspace.
+
+## Development
+
+```bash
+# Build the package
+pnpm build
+
+# Run tests
+pnpm test
+
+# Run in watch mode
+pnpm dev
+```
+
+# Model SDK
+
+## Core Pattern
+
+### Option A: OpenAI-Compatible APIs (easiest)
+
+Pass config directly to `supplyModel` for providers that follow the OpenAI API format:
+
+```typescript
+import { supplyModel } from '@n8n/ai-utilities';
+
+return supplyModel(this, {
+  type: 'openai',
+  modelId: 'model-name',
+  apiKey: 'your-api-key',
+  baseURL: 'https://api.provider.com/v1',  // OpenRouter, DeepSeek, etc.
+});
+```
+
+### Option B: Custom API (full control)
+
+Extend `BaseChatModel` and implement `generate()` + `stream()`:
+
+```typescript
+import { BaseChatModel, supplyModel, type Message, type GenerateResult, type StreamChunk } from '@n8n/ai-utilities';
+
+class MyChatModel extends BaseChatModel {
+  async generate(messages: Message[]): Promise<GenerateResult> {
+    // Call your API, convert messages to provider format...
+    return { text: '...', toolCalls: [...] };
+  }
+
+  async *stream(messages: Message[]): AsyncIterable<StreamChunk> {
+    // Stream from your API...
+    yield { type: 'text-delta', textDelta: '...' };
+    yield { type: 'finish', finishReason: 'stop' };
+  }
+}
+
+const model = new MyChatModel('my-provider', 'model-id', { apiKey: '...' });
+return supplyModel(this, model);
+```
+
+---
+
+## Before/After Examples
+
+### Example 1: LmChatOpenRouter
+
+**Before (LangChain):**
+
+```typescript
+import { ChatOpenAI } from '@langchain/openai';
+import { N8nLlmTracing } from '../N8nLlmTracing';
+
+async supplyData(this: ISupplyDataFunctions, itemIndex: number): Promise<SupplyData> {
+  const credentials = await this.getCredentials<OpenAICompatibleCredential>('openRouterApi');
+  const modelName = this.getNodeParameter('model', itemIndex) as string;
+  const options = this.getNodeParameter('options', itemIndex, {}) as { ... };
+
+  const model = new ChatOpenAI({
+    apiKey: credentials.apiKey,
+    model: modelName,
+    ...options,
+    configuration: { baseURL: credentials.url, ... },
+    callbacks: [new N8nLlmTracing(this)],
+    onFailedAttempt: makeN8nLlmFailedAttemptHandler(this, openAiFailedAttemptHandler),
+  });
+
+  return { response: model };
+}
+```
+
+**After (SDK):**
+
+```typescript
+import { supplyModel } from '@n8n/ai-utilities';
+
+async supplyData(this: ISupplyDataFunctions, itemIndex: number): Promise<SupplyData> {
+  const credentials = await this.getCredentials<{ url: string; apiKey: string }>('openRouterApi');
+  const modelName = this.getNodeParameter('model', itemIndex) as string;
+  const options = this.getNodeParameter('options', itemIndex, {}) as { temperature?: number };
+
+  return supplyModel(this, {
+    type: 'openai',
+    modelId: modelName,
+    apiKey: credentials.apiKey,
+    baseURL: credentials.url,
+    ...options,
+  });
+}
+```
+
+> **Note:** `type: 'openai'` uses the SDK's built-in OpenAI-compatible implementation.
+> Works with OpenRouter, DeepSeek, Azure OpenAI, and any provider following the OpenAI API format.
+
+---
+
+## Community Node Examples
+
+### ImaginaryLLM Chat Model
+
+```typescript
+import {
+  BaseChatModel,
+  supplyModel,
+  type Message,
+  type GenerateResult,
+  type StreamChunk,
+  type ChatModelConfig,
+} from '@n8n/ai-utilities';
+import { NodeConnectionTypes, type INodeType, type ISupplyDataFunctions, type SupplyData } from 'n8n-workflow';
+
+// Custom chat model extending BaseChatModel
+class ImaginaryLlmChatModel extends BaseChatModel {
+  constructor(
+    private apiKey: string,
+    modelId: string,
+    config?: ChatModelConfig,
+  ) {
+    super('imaginary-llm', modelId, config);
+  }
+
+  async generate(messages: Message[], config?: ChatModelConfig): Promise<GenerateResult> {
+    // Convert n8n messages to provider format
+    const providerMessages = messages.map(m => ({
+      speaker: m.role === 'human' ? 'user' : m.role === 'ai' ? 'bot' : m.role,
+      text: m.content.find(c => c.type === 'text')?.text ?? '',
+    }));
+
+    // Call the API
+    const response = await fetch('https://api.imaginary-llm.example.com/v1/generate', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: this.modelId,
+        conversation: providerMessages,
+        settings: {
+          creativity: config?.temperature ?? 0.7,
+          max_length: config?.maxTokens,
+        },
+      }),
+    });
+
+    const data = await response.json();
+
+    return {
+      text: data.reply.text,
+      toolCalls: data.reply.actions?.map((a: any) => ({
+        id: a.id,
+        name: a.name,
+        arguments: a.params,
+      })),
+      usage: data.metrics ? {
+        promptTokens: data.metrics.input_tokens,
+        completionTokens: data.metrics.output_tokens,
+        totalTokens: data.metrics.input_tokens + data.metrics.output_tokens,
+      } : undefined,
+    };
+  }
+
+  async *stream(messages: Message[], config?: ChatModelConfig): AsyncIterable<StreamChunk> {
+    // Streaming implementation...
+    yield { type: 'text-delta', textDelta: '...' };
+    yield { type: 'finish', finishReason: 'stop' };
+  }
+}
+
+// The n8n node
+export class LmChatImaginaryLlm implements INodeType {
+  description = {
+    displayName: 'ImaginaryLLM Chat Model',
+    name: 'lmChatImaginaryLlm',
+    outputs: [NodeConnectionTypes.AiLanguageModel],
+    credentials: [{ name: 'imaginaryLlmApi', required: true }],
+    properties: [
+      { displayName: 'Model', name: 'model', type: 'options', options: [
+        { name: 'Imaginary Pro', value: 'imaginary-pro' },
+        { name: 'Imaginary Fast', value: 'imaginary-fast' },
+      ], default: 'imaginary-pro' },
+      { displayName: 'Temperature', name: 'temperature', type: 'number', default: 0.7 },
+    ],
+  };
+
+  async supplyData(this: ISupplyDataFunctions, itemIndex: number): Promise<SupplyData> {
+    const credentials = await this.getCredentials<{ apiKey: string }>('imaginaryLlmApi');
+    const modelName = this.getNodeParameter('model', itemIndex) as string;
+    const temperature = this.getNodeParameter('temperature', itemIndex) as number;
+
+    const model = new ImaginaryLlmChatModel(credentials.apiKey, modelName, { temperature });
+
+    return supplyModel(this, model);
+  }
+}
+```
+
+---
+
+# Memory SDK
+
+The Memory SDK provides abstractions for building conversation memory nodes without LangChain dependencies.
+
+## Architecture
+
+Memory uses a **two-layer design**:
+
+1. **ChatHistory** (Storage Layer) - Where messages are stored (your custom implementation)
+2. **ChatMemory** (Logic Layer) - How messages are managed (windowing, session scoping)
+
+### Naming Convention
+
+The SDK uses n8n-specific naming to avoid confusion with LangChain classes:
+
+| n8n SDK | LangChain Equivalent |
+|---------|---------------------|
+| `ChatHistory` (interface) | `BaseChatMessageHistory` |
+| `BaseChatHistory` (base class) | `BaseChatMessageHistory` |
+| `ChatMemory` (interface) | `BaseChatMemory` |
+| `BaseChatMemory` (base class) | `BaseChatMemory` |
+| `WindowedChatMemory` | `BufferWindowMemory` |
+
+## Core Pattern
+
+### Option A: Custom Storage
+
+For exotic databases not covered by the SDK, extend `BaseChatHistory`:
+
+```typescript
+import {
+  BaseChatHistory,
+  WindowedChatMemory,
+  supplyMemory,
+  type Message,
+} from '@n8n/ai-utilities';
+
+class MyChatHistory extends BaseChatHistory {
+  constructor(private sessionId: string) {
+    super();
+  }
+
+  async getMessages(): Promise<Message[]> {
+    // Read from your storage...
+    return [];
+  }
+
+  async addMessage(message: Message): Promise<void> {
+    // Write to your storage...
+  }
+
+  async clear(): Promise<void> {
+    // Clear your storage...
+  }
+}
+
+const history = new MyChatHistory(sessionId);
+const memory = new WindowedChatMemory(history, { windowSize: 10 });
+return supplyMemory(this, memory);
+```
+
+### Option B: Custom Memory Logic
+
+For custom memory behavior (not just storage), extend `BaseChatMemory`:
+
+```typescript
+import {
+  BaseChatMemory,
+  supplyMemory,
+  type Message,
+  type ChatHistory,
+  type ChatMemory,
+} from '@n8n/ai-utilities';
+
+class MyCustomChatMemory extends BaseChatMemory {
+  readonly chatHistory: ChatHistory;
+
+  constructor(chatHistory: ChatHistory) {
+    super();
+    this.chatHistory = chatHistory;
+  }
+
+  async loadMessages(): Promise<Message[]> {
+    const messages = await this.chatHistory.getMessages();
+    // Apply your custom logic here...
+    return messages;
+  }
+
+  async saveTurn(input: string, output: string): Promise<void> {
+    await this.chatHistory.addMessages([
+      { role: 'human', content: [{ type: 'text', text: input }] },
+      { role: 'ai', content: [{ type: 'text', text: output }] },
+    ]);
+  }
+
+  async clear(): Promise<void> {
+    await this.chatHistory.clear();
+  }
+}
+
+const history = new MyChatHistory(sessionId);
+const memory = new MyCustomChatMemory(history);
+return supplyMemory(this, memory);
+```
+
+---
+
+## Community Node Examples
+
+### ImaginaryDB Memory Node
+
+```typescript
+import {
+  BaseChatHistory,
+  WindowedChatMemory,
+  supplyMemory,
+  type Message,
+} from '@n8n/ai-utilities';
+import { 
+  NodeConnectionTypes, 
+  type INodeType, 
+  type ISupplyDataFunctions, 
+  type SupplyData,
+  type IHttpRequestMethods,
+} from 'n8n-workflow';
+
+// Custom storage implementation using n8n's HTTP helpers
+class ImaginaryDbChatHistory extends BaseChatHistory {
+  constructor(
+    private sessionId: string,
+    private baseUrl: string,
+    private apiKey: string,
+    private httpRequest: ISupplyDataFunctions['helpers']['httpRequest'],
+  ) {
+    super();
+  }
+
+  async getMessages(): Promise<Message[]> {
+    const data = await this.httpRequest({
+      method: 'GET',
+      url: `${this.baseUrl}/sessions/${this.sessionId}/messages`,
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+      json: true,
+    });
+
+    // Convert from provider format to n8n Message format
+    return data.messages.map((m: any) => ({
+      role: m.speaker === 'user' ? 'human' : m.speaker === 'bot' ? 'ai' : m.speaker,
+      content: [{ type: 'text', text: m.text }],
+    }));
+  }
+
+  async addMessage(message: Message): Promise<void> {
+    const text = message.content.find((c) => c.type === 'text')?.text ?? '';
+    await this.httpRequest({
+      method: 'POST',
+      url: `${this.baseUrl}/sessions/${this.sessionId}/messages`,
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+      body: {
+        speaker: message.role === 'human' ? 'user' : message.role === 'ai' ? 'bot' : message.role,
+        text,
+      },
+      json: true,
+    });
+  }
+
+  async clear(): Promise<void> {
+    await this.httpRequest({
+      method: 'DELETE',
+      url: `${this.baseUrl}/sessions/${this.sessionId}`,
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+  }
+}
+
+// The n8n node
+export class MemoryImaginaryDb implements INodeType {
+  description = {
+    displayName: 'ImaginaryDB Memory',
+    name: 'memoryImaginaryDb',
+    icon: 'file:imaginarydb.svg',
+    group: ['transform'],
+    version: 1,
+    description: 'Use ImaginaryDB for chat memory storage',
+    defaults: { name: 'ImaginaryDB Memory' },
+    codex: { categories: ['AI'], subcategories: { AI: ['Memory'] } },
+    inputs: [],
+    outputs: [NodeConnectionTypes.AiMemory],
+    outputNames: ['Memory'],
+    credentials: [{ name: 'imaginaryDbApi', required: true }],
+    properties: [
+      {
+        displayName: 'Session ID',
+        name: 'sessionId',
+        type: 'string',
+        default: '={{ $json.sessionId }}',
+        description: 'Unique identifier for the conversation session',
+      },
+      {
+        displayName: 'Window Size',
+        name: 'windowSize',
+        type: 'number',
+        default: 10,
+        description: 'Number of recent message pairs to keep in context',
+      },
+    ],
+  };
+
+  async supplyData(this: ISupplyDataFunctions, itemIndex: number): Promise<SupplyData> {
+    const credentials = await this.getCredentials<{ apiKey: string; baseUrl: string }>('imaginaryDbApi');
+    const sessionId = this.getNodeParameter('sessionId', itemIndex) as string;
+    const windowSize = this.getNodeParameter('windowSize', itemIndex) as number;
+
+    // Pass n8n's HTTP request helper directly
+    const history = new ImaginaryDbChatHistory(
+      sessionId,
+      credentials.baseUrl,
+      credentials.apiKey,
+      this.helpers.httpRequest,
+    );
+    const memory = new WindowedChatMemory(history, { windowSize });
+
+    return supplyMemory(this, memory);
+  }
+}
+```
+
+> **Note:** Community nodes must use `this.helpers.httpRequest` or `this.helpers.httpRequestWithAuthentication`
+> for HTTP calls. Direct `fetch` or other global APIs are not allowed.
+
+
+---
+
+## Summary
+
+| Before (LangChain) | After (SDK) |
+|--------------------|-------------|
+| `import { ChatOpenAI } from '@langchain/openai'` | `import { supplyModel } from '@n8n/ai-utilities'` |
+| `new ChatOpenAI({ ... })` | `supplyModel(this, { type: 'openai', ... })` |
+| Custom model provider | `class MyModel extends BaseChatModel { ... }` |
+| `return { response: model }` | `return supplyModel(this, model)` |
+| `import { BufferWindowMemory } from '@langchain/classic/memory'` | `import { WindowedChatMemory } from '@n8n/ai-utilities'` |
+| Custom storage backend | `class MyHistory extends BaseChatHistory { ... }` |
+| `return { response: logWrapper(memory, this) }` | `return supplyMemory(this, memory)` |
+| LangChain message types | `Message` with roles: `system`, `human`, `ai`, `tool` |
+| `tool_calls[].args` | `toolCalls[].arguments` |

package/dist/adapters/langchain-chat-model.d.ts

@@ -0,0 +1,20 @@
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import type { BaseLanguageModelInput } from '@langchain/core/language_models/base';
+import type { BindToolsInput } from '@langchain/core/language_models/chat_models';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { BaseMessage } from '@langchain/core/messages';
+import { AIMessageChunk } from '@langchain/core/messages';
+import type { ChatResult } from '@langchain/core/outputs';
+import { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { Runnable } from '@langchain/core/runnables';
+import type { ISupplyDataFunctions } from 'n8n-workflow';
+import type { ChatModel, ChatModelConfig } from '../types/chat-model';
+export declare class LangchainAdapter<CallOptions extends ChatModelConfig = ChatModelConfig> extends BaseChatModel<CallOptions> {
+    private chatModel;
+    private ctx?;
+    constructor(chatModel: ChatModel, ctx?: ISupplyDataFunctions | undefined);
+    _llmType(): string;
+    _generate(messages: BaseMessage[], options: this['ParsedCallOptions']): Promise<ChatResult>;
+    _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
+    bindTools(tools: BindToolsInput[]): Runnable<BaseLanguageModelInput, AIMessageChunk, CallOptions>;
+}