@atom8n/ai-workflow-builder 1.4.3 → 1.5.1

package/dist/prompts/chains/parameter-updater/guides/predecessor-output.d.ts

@@ -0,0 +1,2 @@
+import type { NodeTypeGuide } from '../types';
+export declare const PREDECESSOR_OUTPUT_GUIDE: NodeTypeGuide;

package/dist/prompts/chains/parameter-updater/guides/predecessor-output.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREDECESSOR_OUTPUT_GUIDE = void 0;
+exports.PREDECESSOR_OUTPUT_GUIDE = {
+    patterns: ['*'],
+    content: `
+### Referencing Output from Special Node Types
+
+#### AI Agent Output Structure
+AI Agent nodes (n8n-nodes-langchain.agent) wrap their response in an "output" object:
+- Without Structured Output Parser: Use \`$json.output\` to access the response string
+- With Structured Output Parser (hasOutputParser: true in node settings): Use \`$json.output.fieldName\` to access parsed fields
+- Use \`$('AI Agent').item.json.output.fieldName\` when referencing a node, instead of \`$('AI Agent').item.json.fieldName\`
+- WRONG: \`$json.summary\` → CORRECT: \`$json.output.summary\`
+
+#### Webhook Node Output Structure
+When referencing data from a Webhook node (n8n-nodes-base.webhook), the incoming request is structured under \`$json\`:
+- \`$json.headers\` - HTTP headers, example: \`$json.headers.authorization\`
+- \`$json.params\` - URL path parameters, example route: \`/users/:id\`, access: \`$json.params.id\`
+- \`$json.query\` - Query string parameters, example URL: \`?user_id=123\`, access: \`$json.query.user_id\`
+- \`$json.body\` - Request payload, example JSON: \`{ "userName": "sam" }\`, access: \`$json.body.userName\`
+
+CRITICAL: When referencing data from a Webhook node, do NOT use \`$json.fieldName\` directly - always specify the container (body, query, params, or headers).`,
+};

package/dist/prompts/shared/node-guidance/index.d.ts

@@ -0,0 +1 @@
+export { structuredOutputParser } from './structured-output-parser';

package/dist/prompts/shared/node-guidance/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.structuredOutputParser = void 0;
+var structured_output_parser_1 = require("./structured-output-parser");
+Object.defineProperty(exports, "structuredOutputParser", { enumerable: true, get: function () { return structured_output_parser_1.structuredOutputParser; } });

package/dist/prompts/shared/node-guidance/structured-output-parser.d.ts

@@ -0,0 +1,2 @@
+import type { NodeGuidance } from '../../../types';
+export declare const structuredOutputParser: NodeGuidance;

package/dist/prompts/shared/node-guidance/structured-output-parser.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.structuredOutputParser = void 0;
+exports.structuredOutputParser = {
+    nodeType: '@n8n/n8n-nodes-langchain.outputParserStructured',
+    usage: `Search for "Structured Output Parser" (@n8n/n8n-nodes-langchain.outputParserStructured) when:
+- AI output will be used programmatically (conditions, formatting, database storage, API calls)
+- AI needs to extract specific fields (e.g., score, category, priority, action items)
+- AI needs to classify/categorize data into defined categories
+- Downstream nodes need to access specific fields from AI response (e.g., $json.score, $json.category)
+- Output will be displayed in a formatted way (e.g., HTML email with specific sections)
+- Data needs validation against a schema before processing
+
+- Always use search_nodes to find the exact node names and versions - NEVER guess versions`,
+    connections: `When Discovery results include AI Agent or Structured Output Parser:
+1. Create the Structured Output Parser node
+2. Set AI Agent's hasOutputParser: true in initialParameters
+3. Connect: Structured Output Parser → AI Agent (ai_outputParser connection)`,
+    configuration: `WHEN TO SET hasOutputParser: true on AI Agent:
+- Discovery found Structured Output Parser node → MUST set hasOutputParser: true
+- AI output will be used in conditions (IF/Switch nodes checking $json.field)
+- AI output will be formatted/displayed (HTML emails, reports with specific sections)
+- AI output will be stored in database/data tables with specific fields
+- AI is classifying, scoring, or extracting specific data fields`,
+    recommendation: `For AI-generated structured data, prefer Structured Output Parser nodes over Code nodes.
+Why: Purpose-built parsers are more reliable and handle edge cases better than custom code.
+
+For binary file data, use Extract From File node to extract content from files before processing.
+
+Use Code nodes only for:
+- Simple string manipulations
+- Already structured data (JSON, CSV)
+- Custom business logic beyond parsing`,
+};

package/dist/prompts/shared/node-recommendations/audio-generation.d.ts

@@ -0,0 +1,2 @@
+import { type NodeRecommendationDocument } from '../../../types/node-recommendations';
+export declare const audioGenerationRecommendation: NodeRecommendationDocument;

package/dist/prompts/shared/node-recommendations/audio-generation.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.audioGenerationRecommendation = void 0;
+const node_recommendations_1 = require("../../../types/node-recommendations");
+exports.audioGenerationRecommendation = {
+    category: node_recommendations_1.RecommendationCategory.AUDIO_GENERATION,
+    version: '1.0.0',
+    recommendation: {
+        defaultNode: '@n8n/n8n-nodes-langchain.openAi',
+        operations: [
+            'Generate Audio: Create speech from text using OpenAI TTS',
+            'Transcribe a Recording: Convert audio to text using Whisper',
+            'Translate a Recording: Transcribe and translate audio to English using Whisper',
+        ],
+        reasoning: "OpenAI provides comprehensive audio capabilities: TTS for speech generation, Whisper for transcription and translation. Prefer OpenAI when user doesn't specify a provider.",
+    },
+};

package/dist/prompts/shared/node-recommendations/image-generation.d.ts

@@ -0,0 +1,2 @@
+import { type NodeRecommendationDocument } from '../../../types/node-recommendations';
+export declare const imageGenerationRecommendation: NodeRecommendationDocument;

package/dist/prompts/shared/node-recommendations/image-generation.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.imageGenerationRecommendation = void 0;
+const node_recommendations_1 = require("../../../types/node-recommendations");
+exports.imageGenerationRecommendation = {
+    category: node_recommendations_1.RecommendationCategory.IMAGE_GENERATION,
+    version: '1.0.0',
+    recommendation: {
+        defaultNode: '@n8n/n8n-nodes-langchain.openAi',
+        operations: [
+            'Analyze Image: Analyze and describe image content using GPT-4 Vision',
+            'Generate an Image: Create images from text prompts using DALL-E',
+            'Edit Image: Modify existing images using DALL-E',
+        ],
+        reasoning: "OpenAI provides comprehensive image capabilities: DALL-E for generation/editing, GPT-4 Vision for analysis. Prefer OpenAI when user doesn't specify a provider.",
+    },
+};

package/dist/prompts/shared/node-recommendations/index.d.ts

@@ -0,0 +1,3 @@
+import { type RecommendationCategoryType, type NodeRecommendationDocument } from '../../../types';
+export { formatRecommendation } from './utils/format-recommendation';
+export declare const recommendations: Record<RecommendationCategoryType, NodeRecommendationDocument | undefined>;

package/dist/prompts/shared/node-recommendations/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recommendations = exports.formatRecommendation = void 0;
+const types_1 = require("../../../types");
+const audio_generation_1 = require("./audio-generation");
+const image_generation_1 = require("./image-generation");
+const text_manipulation_1 = require("./text-manipulation");
+const video_generation_1 = require("./video-generation");
+var format_recommendation_1 = require("./utils/format-recommendation");
+Object.defineProperty(exports, "formatRecommendation", { enumerable: true, get: function () { return format_recommendation_1.formatRecommendation; } });
+exports.recommendations = {
+    [types_1.RecommendationCategory.TEXT_MANIPULATION]: text_manipulation_1.textManipulationRecommendation,
+    [types_1.RecommendationCategory.IMAGE_GENERATION]: image_generation_1.imageGenerationRecommendation,
+    [types_1.RecommendationCategory.VIDEO_GENERATION]: video_generation_1.videoGenerationRecommendation,
+    [types_1.RecommendationCategory.AUDIO_GENERATION]: audio_generation_1.audioGenerationRecommendation,
+};

package/dist/prompts/shared/node-recommendations/text-manipulation.d.ts

@@ -0,0 +1,2 @@
+import { type NodeRecommendationDocument } from '../../../types/node-recommendations';
+export declare const textManipulationRecommendation: NodeRecommendationDocument;

package/dist/prompts/shared/node-recommendations/text-manipulation.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.textManipulationRecommendation = void 0;
+const node_recommendations_1 = require("../../../types/node-recommendations");
+exports.textManipulationRecommendation = {
+    category: node_recommendations_1.RecommendationCategory.TEXT_MANIPULATION,
+    version: '1.0.0',
+    recommendation: {
+        defaultNode: '@n8n/n8n-nodes-langchain.agent',
+        operations: [
+            'Text summarization',
+            'Content analysis and extraction',
+            'Classification and categorization',
+            'Chat and conversational AI',
+            'Content generation and writing',
+        ],
+        reasoning: 'The AI Agent node is the default for text manipulation tasks. New users receive free OpenAI credits. Do NOT use provider-specific nodes directly.',
+        connectedNodes: [
+            {
+                nodeType: '@n8n/n8n-nodes-langchain.lmChatOpenAi',
+                connectionType: 'ai_languageModel',
+                description: 'Required chat model for the AI Agent',
+            },
+        ],
+    },
+};

package/dist/prompts/shared/node-recommendations/utils/format-recommendation.d.ts

@@ -0,0 +1,2 @@
+import type { NodeRecommendation } from '../../../../types';
+export declare function formatRecommendation(rec: NodeRecommendation): string;

package/dist/prompts/shared/node-recommendations/utils/format-recommendation.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatRecommendation = formatRecommendation;
+const builder_1 = require("../../../../prompts/builder");
+function formatRecommendation(rec) {
+    const builder = (0, builder_1.prompt)()
+        .section('default_node', rec.defaultNode)
+        .section('operations', rec.operations.map((op) => `- ${op}`).join('\n'))
+        .section('reasoning', rec.reasoning);
+    if (rec.connectedNodes && rec.connectedNodes.length > 0) {
+        const connectedContent = rec.connectedNodes
+            .map((cn) => {
+            const desc = cn.description ? ` - ${cn.description}` : '';
+            return `- ${cn.nodeType} (connection: ${cn.connectionType})${desc}`;
+        })
+            .join('\n');
+        builder.section('connected_nodes', connectedContent);
+    }
+    if (rec.note) {
+        builder.section('note', rec.note);
+    }
+    return builder.build();
+}

package/dist/prompts/shared/node-recommendations/video-generation.d.ts

@@ -0,0 +1,2 @@
+import { type NodeRecommendationDocument } from '../../../types/node-recommendations';
+export declare const videoGenerationRecommendation: NodeRecommendationDocument;

package/dist/prompts/shared/node-recommendations/video-generation.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.videoGenerationRecommendation = void 0;
+const node_recommendations_1 = require("../../../types/node-recommendations");
+exports.videoGenerationRecommendation = {
+    category: node_recommendations_1.RecommendationCategory.VIDEO_GENERATION,
+    version: '1.0.0',
+    recommendation: {
+        defaultNode: '@n8n/n8n-nodes-langchain.openAi',
+        operations: ['Generate a Video: Create videos from text prompts using Sora'],
+        reasoning: "OpenAI Sora is the default for video generation. Prefer OpenAI when user doesn't specify a provider.",
+        note: 'Video generation may require async processing with Wait nodes due to longer generation times.',
+    },
+};

package/dist/tools/best-practices/data-persistence.d.ts

@@ -0,0 +1,7 @@
+import type { BestPracticesDocument } from '../../types/best-practices';
+export declare class DataPersistenceBestPractices implements BestPracticesDocument {
+    readonly technique: "data_persistence";
+    readonly version = "1.0.0";
+    private readonly documentation;
+    getDocumentation(): string;
+}

package/dist/tools/best-practices/data-persistence.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataPersistenceBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class DataPersistenceBestPractices {
+    technique = categorization_1.WorkflowTechnique.DATA_PERSISTENCE;
+    version = '1.0.0';
+    documentation = `# Best Practices: Data Persistence
+
+## Overview
+
+Data persistence involves storing, updating, or retrieving records from durable storage systems. This technique is essential when you need to maintain data beyond the lifetime of a single workflow execution, or when you need to access existing data that users have stored in their spreadsheets, tables, or databases as part of your workflow logic.
+
+## When to Use Data Persistence
+
+Use data persistence when you need to:
+- Store workflow results for later retrieval or audit trails
+- Maintain records that multiple workflows can access and update
+- Create a centralized data repository for your automation
+- Archive historical data for reporting or compliance
+- Build data that persists across workflow executions
+- Track changes or maintain state over time
+- Store raw form inputs
+
+## Choosing the Right Storage Node
+
+### Data Table (n8n-nodes-base.dataTable) - PREFERRED
+
+**Best for:** Quick setup, small to medium amounts of data
+
+Advantages:
+- No credentials or external configuration required
+- Built directly into n8n
+- Fast and reliable for small to medium datasets
+- Ideal for prototyping and internal workflows
+- No additional costs or external dependencies
+
+When to use:
+- Internal workflow data storage
+- Temporary or staging data
+- Admin/audit trails
+- Simple record keeping
+- Development and testing
+
+### Google Sheets (n8n-nodes-base.googleSheets)
+
+**Best for:** Collaboration, reporting, easy data sharing
+
+Advantages:
+- Familiar spreadsheet interface for non-technical users
+- Easy to share and collaborate on data
+- Built-in visualization and formula capabilities
+- Good for reporting and dashboards
+- Accessible from anywhere
+
+When to use:
+- Data needs to be viewed/edited by multiple people
+- Non-technical users need access to data
+- Integration with other Google Workspace tools
+- Simple data structures without complex relationships
+- Workflow needs access to existing spreadsheets in Google Sheets
+
+Pitfalls:
+- API rate limits can affect high-volume workflows
+- Not suitable for frequently changing data
+- Performance degrades with very large datasets (>10k rows)
+
+### Airtable (n8n-nodes-base.airtable)
+
+**Best for:** Structured data with relationships, rich field types
+
+Advantages:
+- Supports relationships between tables
+- Rich field types (attachments, select, links, etc.)
+- Better structure than spreadsheets
+
+When to use:
+- Data has relationships or references between records
+- Need structured database-like features
+- Managing projects, tasks, or inventory
+- Workflow needs access to existing data in Airtable
+
+Pitfalls:
+- Requires Airtable account and API key
+- Schema changes require careful planning
+
+## Storage Patterns
+
+### Immediate Storage Pattern
+
+Store data immediately after collection or generation:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Process_Data["Process Data"]
+    Process_Data --> Storage_Node["Storage Node"]
+    Storage_Node --> Continue_Workflow["Continue Workflow"]
+\`\`\`
+
+Best for: Raw data preservation, audit trails, form submissions
+
+### Batch Storage Pattern
+
+Collect multiple items and store them together:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Loop_Split["Loop/Split"]
+    Loop_Split --> Process["Process"]
+    Process --> Aggregate["Aggregate"]
+    Aggregate --> Storage_Node["Storage Node"]
+\`\`\`
+
+Best for: Processing lists, batch operations, scheduled aggregations
+
+### Update Pattern
+
+Retrieve, modify, and update existing records:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Retrieve["Retrieve from Storage"]
+    Retrieve --> Modify["Modify"]
+    Modify --> Update_Storage["Update Storage Node"]
+\`\`\`
+
+Best for: Maintaining state, updating records, tracking changes
+
+### Lookup Pattern
+
+Query storage to retrieve specific records:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Query_Storage["Query Storage Node"]
+    Query_Storage --> Use_Data["Use Retrieved Data"]
+    Use_Data --> Continue_Workflow["Continue Workflow"]
+\`\`\`
+
+Best for: Enrichment, validation, conditional logic based on stored data
+
+## Key Considerations
+
+### Data Structure
+
+- **Plan your schema ahead:** Define what fields you need before creating storage
+- **Use consistent field names:** Match field names across your workflow for easy mapping
+- **Consider data types:** Ensure your storage supports the data types you need
+- **Think about relationships:** If data is related, consider Airtable or use multiple tables
+
+### Performance
+
+- **Batch operations when possible:** Multiple small writes are slower than batch operations
+- **Use appropriate operations:** Use "append" for new records, "update" for modifications
+- **Consider API limits:** Google Sheets has rate limits; plan accordingly for high-volume workflows
+
+### Data Integrity
+
+- **Store raw data first:** Keep unmodified input before transformations
+- **Handle errors gracefully:** Use error handling to prevent data loss on failures
+- **Validate before storing:** Ensure data quality before persistence
+- **Avoid duplicates:** Use unique identifiers or upsert operations when appropriate
+
+## Referencing Documents, Sheets, or Tables
+
+When configuring storage nodes, use ResourceLocator mode "list". This will allow users to select from existing documents, sheets, or tables rather than passing IDs dynamically.
+Use modes "id", "url" or "name" only when user specifically mentions it in their prompt.
+
+## Important Distinctions
+
+### Storage vs. Transformation
+
+- **Set/Merge nodes are NOT storage:** They transform data in memory only
+- **Storage happens explicitly:** Data won't persist unless you explicitly write it to storage
+
+### Temporary vs. Persistent Storage
+
+- **NOT covered by this technique:** Redis, caching, session storage, in-memory operations
+- **This technique covers:** Durable storage that persists beyond workflow execution
+- **Focus on permanence:** Use these nodes when you need data to survive restarts and be queryable later
+
+## Common Pitfalls to Avoid
+
+### Not Handling Duplicates
+
+Without proper unique identifiers or upsert logic, you may create duplicate records. Use unique IDs or check for existing records before inserting.
+
+### Ignoring Storage Limits
+
+Each storage system has limits (row counts, API rates, file sizes). Design your workflow to work within these constraints or implement pagination/batching.
+`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.DataPersistenceBestPractices = DataPersistenceBestPractices;

package/dist/tools/get-documentation.tool.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import type { BuilderToolBase } from '../utils/stream-processor';
+export declare const DocumentationType: {
+    readonly BEST_PRACTICES: "best_practices";
+    readonly NODE_RECOMMENDATIONS: "node_recommendations";
+};
+export declare const GET_DOCUMENTATION_TOOL: BuilderToolBase;
+export declare function createGetDocumentationTool(): {
+    toolName: string;
+    displayTitle: string;
+    getCustomDisplayTitle?: (values: Record<string, unknown>) => string;
+    tool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        requests: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"best_practices">;
+            techniques: z.ZodArray<z.ZodNativeEnum<{
+                readonly SCHEDULING: "scheduling";
+                readonly CHATBOT: "chatbot";
+                readonly FORM_INPUT: "form_input";
+                readonly SCRAPING_AND_RESEARCH: "scraping_and_research";
+                readonly MONITORING: "monitoring";
+                readonly ENRICHMENT: "enrichment";
+                readonly TRIAGE: "triage";
+                readonly CONTENT_GENERATION: "content_generation";
+                readonly DOCUMENT_PROCESSING: "document_processing";
+                readonly DATA_EXTRACTION: "data_extraction";
+                readonly DATA_ANALYSIS: "data_analysis";
+                readonly DATA_TRANSFORMATION: "data_transformation";
+                readonly DATA_PERSISTENCE: "data_persistence";
+                readonly NOTIFICATION: "notification";
+                readonly KNOWLEDGE_BASE: "knowledge_base";
+                readonly HUMAN_IN_THE_LOOP: "human_in_the_loop";
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        }, {
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"node_recommendations">;
+            categories: z.ZodArray<z.ZodNativeEnum<{
+                readonly TEXT_MANIPULATION: "text_manipulation";
+                readonly IMAGE_GENERATION: "image_generation";
+                readonly VIDEO_GENERATION: "video_generation";
+                readonly AUDIO_GENERATION: "audio_generation";
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            type: "node_recommendations";
+            categories: ("text_manipulation" | "image_generation" | "video_generation" | "audio_generation")[];
+        }, {
+            type: "node_recommendations";
+            categories: ("text_manipulation" | "image_generation" | "video_generation" | "audio_generation")[];
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        requests: ({
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        } | {
+            type: "node_recommendations";
+            categories: ("text_manipulation" | "image_generation" | "video_generation" | "audio_generation")[];
+        })[];
+    }, {
+        requests: ({
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        } | {
+            type: "node_recommendations";
+            categories: ("text_manipulation" | "image_generation" | "video_generation" | "audio_generation")[];
+        })[];
+    }>, unknown, {
+        requests: ({
+            type: "best_practices";
+            techniques: ("scheduling" | "chatbot" | "form_input" | "scraping_and_research" | "monitoring" | "enrichment" | "triage" | "content_generation" | "document_processing" | "data_extraction" | "data_analysis" | "data_transformation" | "data_persistence" | "notification" | "knowledge_base" | "human_in_the_loop")[];
+        } | {
+            type: "node_recommendations";
+            categories: ("text_manipulation" | "image_generation" | "video_generation" | "audio_generation")[];
+        })[];
+    }, import("@langchain/langgraph").Command<unknown, Record<string, unknown>, string>>;
+};