@n8n/ai-utilities 0.3.0 → 0.4.1

package/README.md

@@ -1,10 +1,14 @@
 # @n8n/ai-utilities
 
-Utilities for building AI nodes in n8n.
+Core utilities and abstractions for AI functionality in n8n. This package provides the foundational building blocks used internally by the n8n platform.
 
-## Installation
+This package is reexported from @n8n/ai-node-sdk, that exposes methods and types for public usage.
 
-This package is part of the n8n monorepo and should be installed via the workspace.
+When changing logic in this package, make sure your changes are backwards compatible. What that means:
+- don't remove existing interfaces or properties in them
+- make new properties optional or create new versions of interfaces
+- publicly exposed methods should handle both old and new interfaces
+- when making a breaking change or adding a new public helper function that is exported in `@n8n/ai-node-sdk`, make sure to update `AI_NODE_SDK_VERSION` in `ai-node-sdk-version.ts`
 
 ## Development
 
@@ -19,464 +23,7 @@ pnpm test
 pnpm dev
 ```
 
-## Running examples
 
-```bash
-pnpm build:examples
-```
-
-Update your env file with:
-
-```bash
-N8N_CUSTOM_EXTENSIONS="<PATH_TO_N8N>/packages/@n8n/ai-utilities/dist_examples/examples/nodes"
-```
-
-Start n8n and add "OpenAI Simple" or "OpenAI Custom" to workflows
-
-# Chat 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 === 'user' ? 'user' : m.role === 'assistant' ? '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: 'user', content: [{ type: 'text', text: input }] },
-      { role: 'assistant', 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' ? 'user' : m.speaker === 'bot' ? 'assistant' : 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 === 'user' ? 'user' : message.role === 'assistant' ? '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: ['assistant'], 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
+## Usage
 
-| 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` |
+For public SDK documentation see `@n8n/ai-node-sdk`.

package/dist/{adapters → cjs/adapters}/langchain-chat-model.d.ts

@@ -9,7 +9,7 @@ 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> {
+export declare class LangchainChatModelAdapter<CallOptions extends ChatModelConfig = ChatModelConfig> extends BaseChatModel<CallOptions> {
     private chatModel;
     private ctx?;
     constructor(chatModel: ChatModel, ctx?: ISupplyDataFunctions | undefined);

package/dist/cjs/adapters/langchain-chat-model.js

@@ -0,0 +1,201 @@
+(function (factory) {
+    if (typeof module === "object" && typeof module.exports === "object") {
+        var v = factory(require, exports);
+        if (v !== undefined) module.exports = v;
+    }
+    else if (typeof define === "function" && define.amd) {
+        define(["require", "exports", "@langchain/core/language_models/chat_models", "@langchain/core/messages", "@langchain/core/outputs", "../converters/message", "../converters/tool", "../utils/failed-attempt-handler/n8nLlmFailedAttemptHandler", "../utils/n8n-llm-tracing"], factory);
+    }
+})(function (require, exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.LangchainChatModelAdapter = void 0;
+    const chat_models_1 = require("@langchain/core/language_models/chat_models");
+    const messages_1 = require("@langchain/core/messages");
+    const outputs_1 = require("@langchain/core/outputs");
+    const message_1 = require("../converters/message");
+    const tool_1 = require("../converters/tool");
+    const n8nLlmFailedAttemptHandler_1 = require("../utils/failed-attempt-handler/n8nLlmFailedAttemptHandler");
+    const n8n_llm_tracing_1 = require("../utils/n8n-llm-tracing");
+    class LangchainChatModelAdapter extends chat_models_1.BaseChatModel {
+        constructor(chatModel, ctx) {
+            const params = {
+                ...(ctx
+                    ? {
+                        callbacks: [
+                            new n8n_llm_tracing_1.N8nLlmTracing(ctx, {
+                                tokensUsageParser: (result) => {
+                                    const tokenUsage = result?.llmOutput?.tokenUsage;
+                                    const completionTokens = tokenUsage?.output_tokens ?? 0;
+                                    const promptTokens = tokenUsage?.input_tokens ?? 0;
+                                    return {
+                                        completionTokens,
+                                        promptTokens,
+                                        totalTokens: completionTokens + promptTokens,
+                                    };
+                                },
+                            }),
+                        ],
+                        onFailedAttempt: (0, n8nLlmFailedAttemptHandler_1.makeN8nLlmFailedAttemptHandler)(ctx),
+                    }
+                    : {}),
+            };
+            super(params);
+            this.chatModel = chatModel;
+            this.ctx = ctx;
+        }
+        _llmType() {
+            return 'n8n-chat-model';
+        }
+        async _generate(messages, options) {
+            const transformedMessages = messages.map(message_1.fromLcMessage);
+            const result = await this.chatModel.generate(transformedMessages, options);
+            const lcMessage = (0, message_1.toLcMessage)(result.message);
+            const usage_metadata = result.usage
+                ? {
+                    input_tokens: result.usage.promptTokens ?? 0,
+                    output_tokens: result.usage.completionTokens ?? 0,
+                    total_tokens: result.usage.totalTokens ?? 0,
+                    input_token_details: result.usage.inputTokenDetails
+                        ? {
+                            cache_read: result.usage.inputTokenDetails.cacheRead,
+                        }
+                        : undefined,
+                    output_token_details: result.usage.outputTokenDetails
+                        ? {
+                            reasoning: result.usage.outputTokenDetails.reasoning,
+                        }
+                        : undefined,
+                }
+                : undefined;
+            if (messages_1.AIMessage.isInstance(lcMessage)) {
+                lcMessage.usage_metadata = usage_metadata;
+            }
+            lcMessage.response_metadata = {
+                ...result.providerMetadata,
+                model: this.chatModel.modelId,
+                provider: this.chatModel.provider,
+            };
+            return {
+                generations: [
+                    {
+                        text: lcMessage.text,
+                        message: lcMessage,
+                    },
+                ],
+                llmOutput: {
+                    id: result.id,
+                    tokenUsage: usage_metadata,
+                },
+            };
+        }
+        async *_streamResponseChunks(messages, options, runManager) {
+            const genericMessages = messages.map(message_1.fromLcMessage);
+            const stream = this.chatModel.stream(genericMessages, options);
+            for await (const chunk of stream) {
+                let lcChunk = undefined;
+                if (chunk.type === 'text-delta') {
+                    const content = [
+                        {
+                            type: 'text',
+                            text: chunk.delta,
+                        },
+                    ];
+                    lcChunk = new outputs_1.ChatGenerationChunk({
+                        message: new messages_1.AIMessageChunk({
+                            content,
+                        }),
+                        text: chunk.delta,
+                    });
+                }
+                else if (chunk.type === 'tool-call-delta') {
+                    const tool_call_chunks = [
+                        {
+                            type: 'tool_call_chunk',
+                            id: chunk.id,
+                            name: chunk.name,
+                            args: chunk.argumentsDelta,
+                            index: 0,
+                        },
+                    ];
+                    lcChunk = new outputs_1.ChatGenerationChunk({
+                        message: new messages_1.AIMessageChunk({
+                            content: '',
+                            tool_call_chunks,
+                        }),
+                        text: '',
+                    });
+                }
+                else if (chunk.type === 'finish') {
+                    const usage_metadata = chunk.usage
+                        ? {
+                            input_tokens: chunk.usage.promptTokens ?? 0,
+                            output_tokens: chunk.usage.completionTokens ?? 0,
+                            total_tokens: chunk.usage.totalTokens ?? 0,
+                        }
+                        : undefined;
+                    lcChunk = new outputs_1.ChatGenerationChunk({
+                        message: new messages_1.AIMessageChunk({
+                            content: '',
+                            usage_metadata,
+                            response_metadata: {
+                                finish_reason: chunk.finishReason,
+                            },
+                        }),
+                        text: '',
+                        generationInfo: {
+                            finish_reason: chunk.finishReason,
+                        },
+                    });
+                }
+                else if (chunk.type === 'error') {
+                    lcChunk = new outputs_1.ChatGenerationChunk({
+                        message: new messages_1.AIMessageChunk({
+                            content: '',
+                            response_metadata: {
+                                finish_reason: 'error',
+                                error: chunk.error,
+                            },
+                        }),
+                        text: '',
+                        generationInfo: {
+                            finish_reason: 'error',
+                            error: chunk.error,
+                        },
+                    });
+                }
+                else if (chunk.type === 'content') {
+                    const lcMessage = (0, message_1.toLcMessage)({
+                        role: 'assistant',
+                        content: [chunk.content],
+                        id: chunk.id,
+                    });
+                    const lcMessageChunk = new messages_1.AIMessageChunk({
+                        content: lcMessage.content,
+                        id: lcMessage.id,
+                        name: lcMessage.name,
+                    });
+                    lcChunk = new outputs_1.ChatGenerationChunk({
+                        message: lcMessageChunk,
+                        text: lcMessage.text,
+                    });
+                }
+                if (lcChunk) {
+                    yield lcChunk;
+                    await runManager?.handleLLMNewToken(lcChunk.text ?? '', {
+                        prompt: 0,
+                        completion: 0,
+                    }, undefined, undefined, undefined, { chunk: lcChunk });
+                }
+            }
+        }
+        bindTools(tools) {
+            const genericTools = tools.map(tool_1.fromLcTool);
+            const newModel = this.chatModel.withTools(genericTools);
+            const newAdapter = new LangchainChatModelAdapter(newModel, this.ctx);
+            return newAdapter;
+        }
+    }
+    exports.LangchainChatModelAdapter = LangchainChatModelAdapter;
+});
+//# sourceMappingURL=langchain-chat-model.js.map