@n8n/ai-node-sdk 0.1.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,349 @@
+# @n8n/ai-node-sdk
+
+Public SDK for building AI nodes in n8n. This package provides a simplified API for creating chat model and memory nodes without LangChain dependencies.
+
+## Installation in node packages
+
+Include the package in your node packages by updating `peerDependencies`:
+
+```json
+{
+  "peerDependencies": {
+    "n8n-workflow": "*",
+    "@n8n/ai-node-sdk": "*"
+  }
+}
+```
+
+## Development
+
+```bash
+# Build the package
+pnpm build
+
+# Run tests
+pnpm test
+
+# Run in watch mode
+pnpm dev
+```
+
+## Chat Model Nodes
+
+Chat model nodes implement the `INodeType` interface and use `supplyModel` to provide model instances.
+
+### Simple Pattern: OpenAI-Compatible Providers
+
+For OpenAI-compatible providers, use the config object pattern with `supplyModel`:
+
+```typescript
+import { supplyModel } from '@n8n/ai-node-sdk';
+import {
+  type INodeType,
+  type INodeTypeDescription,
+  NodeConnectionTypes,
+  type SupplyData,
+  type ISupplyDataFunctions,
+} from 'n8n-workflow';
+
+export class LmChatMyProvider implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'MyProvider Chat Model',
+    name: 'lmChatMyProvider',
+    icon: 'fa:robot',
+    group: ['transform'],
+    version: [1],
+    description: 'For advanced usage with an AI chain',
+    defaults: {
+      name: 'MyProvider Chat Model',
+    },
+    inputs: [],
+    outputs: [NodeConnectionTypes.AiLanguageModel],
+    credentials: [{ name: 'myProviderApi', required: true }],
+    properties: [
+      {
+        displayName: 'Model',
+        name: 'model',
+        type: 'string',
+        default: 'my-model',
+      },
+      {
+        displayName: 'Temperature',
+        name: 'temperature',
+        type: 'number',
+        default: 0.7,
+      },
+    ],
+  };
+
+  async supplyData(this: ISupplyDataFunctions, itemIndex: number): Promise<SupplyData> {
+    const credentials = await this.getCredentials('myProviderApi');
+    const model = this.getNodeParameter('model', itemIndex) as string;
+    const temperature = this.getNodeParameter('temperature', itemIndex) as number;
+
+    // Return config for OpenAI-compatible providers
+    return supplyModel(this, {
+      type: 'openai',
+      baseUrl: credentials.url as string,
+      apiKey: credentials.apiKey as string,
+      model,
+      temperature,
+    });
+  }
+}
+```
+
+### Advanced Pattern: Custom Model Class
+
+For providers with custom APIs, extend `BaseChatModel` and pass an instance to `supplyModel`:
+
+```typescript
+import {
+  BaseChatModel,
+  supplyModel,
+  type Message,
+  type GenerateResult,
+  type StreamChunk,
+  type ChatModelConfig,
+} from '@n8n/ai-node-sdk';
+import {
+  type INodeType,
+  type INodeTypeDescription,
+  NodeConnectionTypes,
+  type IHttpRequestMethods,
+  type ISupplyDataFunctions,
+  type SupplyData,
+} from 'n8n-workflow';
+import type Stream from 'node:stream';
+import { Readable } from 'node:stream';
+
+// Custom model implementation
+class MyProviderChatModel extends BaseChatModel {
+  constructor(
+    modelId: string,
+    private requests: {
+      httpRequest: (
+        method: IHttpRequestMethods,
+        url: string,
+        body?: object,
+        headers?: Record<string, string>,
+      ) => Promise<{ body: unknown }>;
+      openStream: (
+        method: IHttpRequestMethods,
+        url: string,
+        body?: object,
+        headers?: Record<string, string>,
+      ) => Promise<{ body: ReadableStream<Uint8Array> }>;
+    },
+    config?: ChatModelConfig,
+  ) {
+    super('my-provider', modelId, config);
+  }
+
+  async generate(messages: Message[], config?: ChatModelConfig): Promise<GenerateResult> {
+    // Convert n8n messages to provider format
+    const providerMessages = messages.map(m => ({
+      role: m.role,
+      content: m.content.find(c => c.type === 'text')?.text ?? '',
+    }));
+
+    // Call the provider API
+    const response = await this.requests.httpRequest('POST', '/chat', {
+      model: this.modelId,
+      messages: providerMessages,
+      temperature: config?.temperature,
+    });
+
+    const body = response.body as any;
+
+    return {
+      finishReason: 'stop',
+      message: {
+        id: body.id,
+        role: 'assistant',
+        content: [{ type: 'text', text: body.content }],
+      },
+      usage: {
+        promptTokens: body.usage.prompt_tokens,
+        completionTokens: body.usage.completion_tokens,
+        totalTokens: body.usage.total_tokens,
+      },
+    };
+  }
+
+  async *stream(messages: Message[], config?: ChatModelConfig): AsyncIterable<StreamChunk> {
+    // Implement streaming...
+    yield { type: 'text-delta', delta: 'response text' };
+    yield { type: 'finish', finishReason: 'stop' };
+  }
+}
+
+// Node definition
+export class LmChatMyProvider implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'MyProvider Chat Model',
+    name: 'lmChatMyProvider',
+    icon: 'fa:robot',
+    group: ['transform'],
+    version: [1],
+    description: 'For advanced usage with an AI chain',
+    defaults: {
+      name: 'MyProvider Chat Model',
+    },
+    inputs: [],
+    outputs: [NodeConnectionTypes.AiLanguageModel],
+    credentials: [{ name: 'myProviderApi', required: true }],
+    properties: [
+      { displayName: 'Model', name: 'model', type: 'string', default: 'my-model' },
+      { displayName: 'Temperature', name: 'temperature', type: 'number', default: 0.7 },
+    ],
+  };
+
+  async supplyData(this: ISupplyDataFunctions, itemIndex: number): Promise<SupplyData> {
+    const model = this.getNodeParameter('model', itemIndex) as string;
+    const temperature = this.getNodeParameter('temperature', itemIndex) as number;
+
+    const chatModel = new MyProviderChatModel(
+      model,
+      {
+        httpRequest: async (method, url, body, headers) => {
+          const response = await this.helpers.httpRequestWithAuthentication.call(
+            this,
+            'myProviderApi',
+            { method, url, body, headers },
+          );
+          return { body: response };
+        },
+        openStream: async (method, url, body, headers) => {
+          const response = (await this.helpers.httpRequestWithAuthentication.call(
+            this,
+            'myProviderApi',
+            { method, url, body, headers, encoding: 'stream' },
+          )) as Stream.Readable;
+          return { body: Readable.toWeb(response) as ReadableStream<Uint8Array> };
+        },
+      },
+      { temperature },
+    );
+
+    return supplyModel(this, chatModel);
+  }
+}
+```
+
+## Memory Nodes
+
+Memory nodes implement the `INodeType` interface and use `supplyMemory` to provide memory instances.
+
+### Pattern: Custom Storage with Windowed Memory
+
+Extend `BaseChatHistory` to implement storage, then wrap it with `WindowedChatMemory` and pass to `supplyMemory`:
+
+```typescript
+import {
+  BaseChatHistory,
+  WindowedChatMemory,
+  supplyMemory,
+  type Message,
+} from '@n8n/ai-node-sdk';
+import {
+  type INodeType,
+  type INodeTypeDescription,
+  NodeConnectionTypes,
+  type ISupplyDataFunctions,
+  type SupplyData,
+} from 'n8n-workflow';
+
+// Custom storage implementation
+class MyDbChatHistory extends BaseChatHistory {
+  constructor(
+    private sessionId: string,
+    private apiKey: string,
+    private httpRequest: any,
+  ) {
+    super();
+  }
+
+  async getMessages(): Promise<Message[]> {
+    const data = await this.httpRequest({
+      method: 'GET',
+      url: `/sessions/${this.sessionId}/messages`,
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+      json: true,
+    });
+
+    return data.messages.map((m: any) => ({
+      role: m.role,
+      content: [{ type: 'text', text: m.content }],
+    }));
+  }
+
+  async addMessage(message: Message): Promise<void> {
+    const text = message.content.find(c => c.type === 'text')?.text ?? '';
+    await this.httpRequest({
+      method: 'POST',
+      url: `/sessions/${this.sessionId}/messages`,
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+      body: { role: message.role, content: text },
+      json: true,
+    });
+  }
+
+  async clear(): Promise<void> {
+    await this.httpRequest({
+      method: 'DELETE',
+      url: `/sessions/${this.sessionId}`,
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+  }
+}
+
+// Memory node
+export class MemoryMyDb implements INodeType {
+  description: INodeTypeDescription = {
+    displayName: 'MyDB Memory',
+    name: 'memoryMyDb',
+    icon: 'fa:database',
+    group: ['transform'],
+    version: [1],
+    description: 'Store conversation history in MyDB',
+    defaults: {
+      name: 'MyDB Memory',
+    },
+    inputs: [],
+    outputs: [NodeConnectionTypes.AiMemory],
+    credentials: [{ name: 'myDbApi', required: true }],
+    properties: [
+      {
+        displayName: 'Session ID',
+        name: 'sessionId',
+        type: 'string',
+        default: '={{ $json.sessionId }}',
+      },
+      {
+        displayName: 'Window Size',
+        name: 'windowSize',
+        type: 'number',
+        default: 10,
+        description: 'Number of recent message pairs to keep',
+      },
+    ],
+  };
+
+  async supplyData(this: ISupplyDataFunctions, itemIndex: number): Promise<SupplyData> {
+    const credentials = await this.getCredentials('myDbApi');
+    const sessionId = this.getNodeParameter('sessionId', itemIndex) as string;
+    const windowSize = this.getNodeParameter('windowSize', itemIndex) as number;
+
+    const history = new MyDbChatHistory(
+      sessionId,
+      credentials.apiKey as string,
+      this.helpers.httpRequest,
+    );
+
+    const memory = new WindowedChatMemory(history, { windowSize });
+
+    return supplyMemory(this, memory);
+  }
+}
+```