@n8n/ai-workflow-builder 0.28.0 → 0.30.0

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

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataExtractionBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class DataExtractionBestPractices {
+    technique = categorization_1.WorkflowTechnique.DATA_EXTRACTION;
+    version = '1.0.0';
+    documentation = `# Best Practices: Data Extraction Workflows
+
+## Node Selection by Data Type
+
+Choose the right node for your data source. Use Extract From File for CSV, Excel, PDF, and text files to convert binary data to JSON for further processing.
+
+Use Information Extractor or AI nodes for extracting structured data from unstructured text such as PDFs or emails using LLMs.
+
+For binary data, ensure you use nodes like Extract From File to handle files properly.
+
+## Data Structure & Type Management
+
+Normalize data structure early in your workflow. Use transformation nodes like Split Out, Aggregate, or Set to ensure your data matches n8n's expected structure: an array of objects with a json key.
+Not transforming incoming data to n8n's expected format causes downstream node failures.
+
+When working with large amounts of information, n8n's display can be hard to view. Use the Edit Fields node to help organize and view data more clearly during development and debugging.
+
+## Large File Handling
+
+Process files in batches or use sub-workflows to avoid memory issues. For large binary files, consider enabling filesystem mode (N8N_DEFAULT_BINARY_DATA_MODE=filesystem) if self-hosted, to store binary data on disk instead of memory.
+
+Processing too many items or large files at once can crash your instance. Always batch or split processing for large datasets to manage memory effectively.
+
+## Binary Data Management
+
+Binary data can be lost if intermediate nodes (like Set or Code) do not have "Include Other Input Fields" enabled, especially in sub-workflows. Always verify binary data is preserved through your workflow pipeline.
+
+## AI-Powered Extraction
+
+Leverage AI for unstructured data using nodes like Information Extractor or Summarization Chain to extract structured data from unstructured sources such as PDFs, emails, or web pages.
+
+## Recommended Nodes
+
+### Extract From File (n8n-nodes-base.extractFromFile)
+
+Purpose: Converts binary data from CSV, Excel, PDF, and text files to JSON for processing
+
+Pitfalls:
+
+- Ensure the correct binary field name is specified in the node configuration
+- Verify file format compatibility before extraction
+
+### HTML Extract (n8n-nodes-base.htmlExtract)
+
+Purpose: Scrapes data from web pages using CSS selectors
+
+### Split Out (n8n-nodes-base.splitOut)
+
+Purpose: Processes arrays of items individually for sequential operations
+
+### Edit Fields (Set) (n8n-nodes-base.set)
+
+Purpose: Data transformation and mapping to normalize structure
+
+Pitfalls:
+
+- Enable "Include Other Input Fields" to preserve binary data
+- Pay attention to data types - mixing types causes unexpected failures
+
+### Information Extractor (@n8n/n8n-nodes-langchain.informationExtractor)
+
+Purpose: AI-powered extraction of structured data from unstructured text
+
+Pitfalls:
+
+- Requires proper schema definition for extraction
+
+### Summarization Chain (@n8n/n8n-nodes-langchain.chainSummarization)
+
+Purpose: Summarizes large text blocks using AI for condensed information extraction
+
+Pitfalls:
+
+- Context window limits may truncate very long documents
+- Verify summary quality matches requirements
+
+### HTTP Request (n8n-nodes-base.httpRequest)
+
+Purpose: Fetches data from APIs or web pages for extraction
+
+### Code (n8n-nodes-base.code)
+
+Purpose: Custom logic for complex data transformations
+
+## Common Pitfalls to Avoid
+
+Data Type Confusion: People often mix up data types - n8n can be very lenient but it can lead to problems. Pay close attention to what type you are getting and ensure consistency throughout the workflow.
+
+Binary Data Loss: Binary data can be lost if intermediate nodes (Set, Code) do not have "Include Other Input Fields" enabled, especially in sub-workflows. Always verify binary data preservation.
+
+Large Data Display Issues: n8n displaying large amounts of information can be hard to view during development. Use the Edit Fields node to help organize and view data more clearly.
+`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.DataExtractionBestPractices = DataExtractionBestPractices;
+//# sourceMappingURL=data-extraction.js.map

package/dist/tools/best-practices/data-extraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-extraction.js","sourceRoot":"","sources":["../../../src/tools/best-practices/data-extraction.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,2BAA2B;IAC9B,SAAS,GAAG,kCAAiB,CAAC,eAAe,CAAC;IAC9C,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2FjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AApGD,kEAoGC"}

package/dist/tools/best-practices/form-input.d.ts

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

package/dist/tools/best-practices/form-input.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormInputBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class FormInputBestPractices {
+    technique = categorization_1.WorkflowTechnique.FORM_INPUT;
+    version = '1.0.0';
+    documentation = `# Best Practices: Form Input Workflows
+
+## Workflow Design
+
+### Critical: Always Store Raw Form Data
+
+ALWAYS store raw form responses to a persistent data storage destination even if the primary purpose of the workflow is
+to trigger another action (like sending to an API or triggering a notification). This allows users to monitor
+form responses as part of the administration of their workflow.
+
+Required storage destinations include:
+- Google Sheets node
+- Airtable node
+- n8n Data Tables
+- PostgreSQL/MySQL/MongoDB nodes
+- Any other database or spreadsheet service
+
+IMPORTANT: Simply using Set or Merge nodes is NOT sufficient. These nodes only transform data in memory - they do not
+persist data. You must use an actual storage node (like Google Sheets, Airtable, or Data Tables) to write the data.
+
+Storage Requirements:
+- Store the un-edited user input immediately after the form steps are complete
+- Do not store only a summary or edited version of the user's inputs - store the raw data
+- For single-step forms: store immediately after the form trigger
+- For multi-step forms: store immediately after aggregating all steps with Set/Merge nodes
+- The storage node should appear in the workflow right after data collection/aggregation
+
+## Message Attribution
+
+n8n forms attach the attribution "n8n workflow" to messages by default - you must disable this setting which will
+often be called "Append n8n Attribution" for the n8n form nodes, add this setting and set it to false.
+
+## Multi-Step Forms
+
+Build multi-step forms by chaining multiple Form nodes together. Each Form node represents a page or step in your form
+sequence. Use the n8n Form Trigger node to start the workflow and display the first form page to the user.
+
+## Data Collection & Aggregation
+
+Collect and merge all user responses from each form step before writing to your destination (e.g., Google Sheets). Use
+Set or Merge nodes to combine data as needed. Make sure your JSON keys match the column names in your destination for
+automatic mapping.
+
+## Conditional Logic & Branching
+
+Use IF or Switch nodes to direct users to different form pages based on their previous answers. This enables dynamic
+form flows where the path changes based on user input, creating personalized form experiences.
+
+## Dynamic Form Fields
+
+For forms that require dynamic options (e.g., dropdowns populated from an API or previous step), generate the form
+definition in a Code node and pass it to the Form node as JSON. You can define forms using JSON for dynamic or
+conditional fields, and even generate form fields dynamically using a Code node if needed.
+
+## Input Validation
+
+Validate user input between steps to ensure data quality. If input is invalid, loop back to the relevant form step with
+an error message to guide the user to correct their submission. This prevents bad data from entering your system.
+
+## Recommended Nodes
+
+### n8n Form Trigger (n8n-nodes-base.formTrigger)
+
+Purpose: Starts the workflow and displays the first form page to the user
+
+Pitfalls:
+
+- Use the Production URL for live forms; the Test URL is for development and debugging only
+- Ensure the form trigger is properly configured before sharing URLs with users
+
+### n8n Form (n8n-nodes-base.form)
+
+Purpose: Displays form pages in multi-step form sequences
+
+Pitfalls:
+
+- Each Form node represents one page/step in your form
+- You can define forms using JSON for dynamic or conditional fields
+- Generate form fields dynamically using a Code node if needed for complex scenarios
+
+### Storage Nodes
+
+Purpose: Persist raw form data to a storage destination, preference should be for built-in n8n tables
+but use the most applicable node depending on the user's request.
+
+Required nodes (use at least one):
+- Data table (n8n-nodes-base.dataTable): Built-in n8n storage for quick setup
+- Google Sheets (n8n-nodes-base.googleSheets): Best for simple spreadsheet storage
+- Airtable (n8n-nodes-base.airtable): Best for structured database with relationships
+- Postgres (n8n-nodes-base.postgres) / MySQL (n8n-nodes-base.mySql) / MongoDB (n8n-nodes-base.mongoDb): For production database storage
+
+Pitfalls:
+
+- Every form workflow MUST include a storage node that actually writes data to a destination
+- Set and Merge nodes alone are NOT sufficient - they only transform data in memory
+- The storage node should be placed immediately after the form trigger (single-step) or after data aggregation (multi-step)
+
+### Code (n8n-nodes-base.code)
+
+Purpose: Processes form data, generates dynamic form definitions, or implements custom validation logic
+
+### Edit Fields (Set) (n8n-nodes-base.set)
+
+Purpose: Aggregates and transforms form data between steps (NOT for storage - use a storage node)
+
+### Merge (n8n-nodes-base.merge)
+
+Purpose: Combines data from multiple form steps into a single dataset (NOT for storage - use a storage node)
+
+Pitfalls:
+
+- Ensure data from all form steps is properly merged before writing to destination
+- Use appropriate merge modes (append, merge by key, etc.) for your use case
+- Remember: Merge prepares data but does not store it - add a storage node after Merge
+
+### If (n8n-nodes-base.if)
+
+Purpose: Routes users to different form pages based on their previous answers
+
+### Switch (n8n-nodes-base.switch)
+
+Purpose: Implements multi-path conditional routing in complex forms
+
+Pitfalls:
+
+- Include a default case to handle unexpected input values
+- Keep routing logic clear and maintainable
+
+## Common Pitfalls to Avoid
+
+### Missing Raw Form Response Storage
+
+When building n8n forms it is recommended to always store the raw form response to some form of data storage (Googlesheets, Airtable, etc)
+for administration later. It is CRITICAL if you create a n8n form node that you store the raw output with a storage node.
+
+### Data Loss in Multi-Step Forms
+
+Aggregate all form step data using Set/Merge nodes before writing to your destination. Failing to merge data from multiple steps
+can result in incomplete form submissions being stored. After merging, ensure you write the complete dataset to a storage node.
+
+### Poor User Experience
+
+Use the Form Ending page type to show a completion message or redirect users after submission.
+Without a proper ending, users may be confused about whether their submission was successful.
+
+### Invalid Data
+
+Implement validation between form steps to catch errors early. Without validation, invalid data can
+propagate through your workflow and corrupt your destination data.
+
+### Complex Field Generation
+
+When generating dynamic form fields, ensure the JSON structure exactly matches what the Form
+node expects. Test thoroughly with the Test URL before going live.
+
+### Mapping Errors
+
+When writing to Google Sheets or other destinations, ensure field names match exactly. Mismatched names
+will cause data to be written to wrong columns or fail entirely.
+`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.FormInputBestPractices = FormInputBestPractices;
+//# sourceMappingURL=form-input.js.map

package/dist/tools/best-practices/form-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-input.js","sourceRoot":"","sources":["../../../src/tools/best-practices/form-input.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,sBAAsB;IACzB,SAAS,GAAG,kCAAiB,CAAC,UAAU,CAAC;IACzC,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+JjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAxKD,wDAwKC"}

package/dist/tools/best-practices/index.d.ts

@@ -0,0 +1,3 @@
+import type { BestPracticesDocument } from '../../types';
+import { type WorkflowTechniqueType } from '../../types/categorization';
+export declare const documentation: Record<WorkflowTechniqueType, BestPracticesDocument | undefined>;

package/dist/tools/best-practices/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.documentation = void 0;
+const categorization_1 = require("../../types/categorization");
+const chatbot_1 = require("./chatbot");
+const content_generation_1 = require("./content-generation");
+const data_extraction_1 = require("./data-extraction");
+const form_input_1 = require("./form-input");
+const scraping_and_research_1 = require("./scraping-and-research");
+exports.documentation = {
+    [categorization_1.WorkflowTechnique.SCRAPING_AND_RESEARCH]: new scraping_and_research_1.ScrapingAndResearchBestPractices(),
+    [categorization_1.WorkflowTechnique.CHATBOT]: new chatbot_1.ChatbotBestPractices(),
+    [categorization_1.WorkflowTechnique.CONTENT_GENERATION]: new content_generation_1.ContentGenerationBestPractices(),
+    [categorization_1.WorkflowTechnique.DATA_EXTRACTION]: new data_extraction_1.DataExtractionBestPractices(),
+    [categorization_1.WorkflowTechnique.FORM_INPUT]: new form_input_1.FormInputBestPractices(),
+    [categorization_1.WorkflowTechnique.DATA_ANALYSIS]: undefined,
+    [categorization_1.WorkflowTechnique.DATA_TRANSFORMATION]: undefined,
+    [categorization_1.WorkflowTechnique.DOCUMENT_PROCESSING]: undefined,
+    [categorization_1.WorkflowTechnique.ENRICHMENT]: undefined,
+    [categorization_1.WorkflowTechnique.HUMAN_IN_THE_LOOP]: undefined,
+    [categorization_1.WorkflowTechnique.KNOWLEDGE_BASE]: undefined,
+    [categorization_1.WorkflowTechnique.MONITORING]: undefined,
+    [categorization_1.WorkflowTechnique.NOTIFICATION]: undefined,
+    [categorization_1.WorkflowTechnique.SCHEDULING]: undefined,
+    [categorization_1.WorkflowTechnique.TRIAGE]: undefined,
+};
+//# sourceMappingURL=index.js.map

package/dist/tools/best-practices/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/best-practices/index.ts"],"names":[],"mappings":";;;AACA,2DAAuF;AAEvF,uCAAiD;AACjD,6DAAsE;AACtE,uDAAgE;AAChE,6CAAsD;AACtD,mEAA2E;AAE9D,QAAA,aAAa,GAAqE;IAC9F,CAAC,kCAAiB,CAAC,qBAAqB,CAAC,EAAE,IAAI,wDAAgC,EAAE;IACjF,CAAC,kCAAiB,CAAC,OAAO,CAAC,EAAE,IAAI,8BAAoB,EAAE;IACvD,CAAC,kCAAiB,CAAC,kBAAkB,CAAC,EAAE,IAAI,mDAA8B,EAAE;IAC5E,CAAC,kCAAiB,CAAC,eAAe,CAAC,EAAE,IAAI,6CAA2B,EAAE;IACtE,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,IAAI,mCAAsB,EAAE;IAG5D,CAAC,kCAAiB,CAAC,aAAa,CAAC,EAAE,SAAS;IAC5C,CAAC,kCAAiB,CAAC,mBAAmB,CAAC,EAAE,SAAS;IAClD,CAAC,kCAAiB,CAAC,mBAAmB,CAAC,EAAE,SAAS;IAClD,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;IACzC,CAAC,kCAAiB,CAAC,iBAAiB,CAAC,EAAE,SAAS;IAChD,CAAC,kCAAiB,CAAC,cAAc,CAAC,EAAE,SAAS;IAC7C,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;IACzC,CAAC,kCAAiB,CAAC,YAAY,CAAC,EAAE,SAAS;IAC3C,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;IACzC,CAAC,kCAAiB,CAAC,MAAM,CAAC,EAAE,SAAS;CACrC,CAAC"}

package/dist/tools/best-practices/scraping-and-research.d.ts

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

package/dist/tools/best-practices/scraping-and-research.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScrapingAndResearchBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class ScrapingAndResearchBestPractices {
+    technique = categorization_1.WorkflowTechnique.SCRAPING_AND_RESEARCH;
+    version = '1.0.0';
+    documentation = `# Best Practices: Scraping & Research Workflows
+
+## Performance & Resource Management
+
+Batch requests and introduce delays to avoid hitting API rate limits or overloading target servers. Use Wait nodes and
+batching options in HTTP Request nodes. When 429 rate limiting errors occur due to receiving too many requests,
+implement batching to reduce request frequency or use the "Retry on Fail" feature to automatically handle throttled
+responses.
+
+Workflows processing large datasets can crash due to memory constraints. Use the Split In Batches node to process 200
+rows at a time to reduce memory usage, leverage built-in nodes instead of custom code, and increase execution timeouts
+via environment variables for better resource management.
+
+## Looping & Pagination
+
+Implement robust looping for paginated data. Use Set, IF, and Code nodes to manage page numbers and loop conditions,
+ensuring you don't miss data or create infinite loops. Leverage n8n's built-in mechanisms rather than manual approaches:
+use the $runIndex variable to track iterations without additional code nodes, and employ workflow static data or node
+run indexes to maintain state across loop cycles.
+
+## Recommended Nodes
+
+### HTTP Request (n8n-nodes-base.httpRequest)
+
+Purpose: Fetches web pages or API data for scraping and research workflows
+
+Pitfalls:
+
+- Depending on the data which the user wishes to scrape/research, it maybe against the terms of service to attempt to
+fetch it from the site directly. Using scraping nodes is the best way to get around this.
+
+Pitfalls:
+
+- Double-check URL formatting, query parameters, and ensure all required fields are present to avoid bad request errors
+- Be aware of 429 rate limiting errors when the service receives too many requests - implement batching or use "Retry on
+Fail" feature
+- Refresh expired tokens, verify API keys, and ensure correct permissions to avoid authentication failures
+
+### HTML Extract (n8n-nodes-base.htmlExtract)
+
+Purpose: Parses HTML and extracts data using CSS selectors for web scraping
+
+Pitfalls:
+
+- Some sites use JavaScript to render content, which may not be accessible via simple HTTP requests. Consider using
+browser automation tools or APIs if the HTML appears empty
+- Validate that the CSS selectors match the actual page structure to avoid extraction failures
+
+### Split Out (n8n-nodes-base.splitOut)
+
+Purpose: Processes lists of items one by one for sequential operations
+
+Pitfalls:
+- Can cause performance issues with very large datasets - consider using Split In Batches instead
+
+### Loop Over Items (Split in Batches) (n8n-nodes-base.splitInBatches)
+
+Purpose: Processes lists of items in batches to manage memory and performance
+
+Pitfalls:
+- Ensure proper loop configuration to avoid infinite loops or skipped data. The index 0
+(first connection) of the loop is treated as the done state, while the index 1 (second connection)
+is the connection that loops.
+- Use appropriate batch sizes (e.g., 200 rows) to balance memory usage and performance
+
+### Edit Fields (Set) (n8n-nodes-base.set)
+
+Purpose: Manipulates data, sets variables for loop control and state management
+
+### Code (n8n-nodes-base.code)
+
+Purpose: Implements custom logic for complex data transformations or pagination
+
+Pitfalls:
+
+- Prefer built-in nodes over custom code to reduce memory usage and improve maintainability
+- Avoid processing very large datasets in a single code execution - use batching
+
+### If (n8n-nodes-base.if)
+
+Purpose: Adds conditional logic for error handling, loop control, or data filtering
+
+Pitfalls:
+- Validate expressions carefully to avoid unexpected branching behavior
+
+### Wait (n8n-nodes-base.wait)
+
+Purpose: Introduces delays to respect rate limits and avoid overloading servers
+
+### Google Sheets (n8n-nodes-base.googleSheets)
+
+Purpose: Stores scraped data in spreadsheets for easy access and sharing
+
+### Microsoft Excel 365 (n8n-nodes-base.microsoftExcel)
+
+Purpose: Stores scraped data in Excel files for offline analysis
+
+### Airtable (n8n-nodes-base.airtable)
+
+Purpose: Saves structured data to a database with rich data types and relationships
+
+### AI Agent (@n8n/n8n-nodes-langchain.agent)
+
+Purpose: For research, summarization, and advanced data extraction. AI agents can autonomously gather information
+from websites, analyze content, and organize findings into structured formats, integrating tools for web scraping,
+content analysis, and database storage
+
+### Scraping Nodes
+
+- Phantombuster (n8n-nodes-base.phantombuster)
+- Apify (use HTTP Request or community node)
+- BrightData (use HTTP Request or community node)
+
+Purpose: If the user wishes to scrap data from sites like LinkedIn, Facebook, Instagram, Twitter/X, Indeed, Glassdoor
+or any other service similar to these large providers it is better to use a node designed for this. The scraping
+nodes provide access to these datasets while avoiding issues like rate limiting or breaking terms of service for
+sites like these.
+
+## Common Pitfalls to Avoid
+
+Bad Request Errors: Double-check URL formatting, query parameters, and ensure all required fields are present to
+avoid 400 errors when making HTTP requests.
+
+Rate Limits: Use batching and Wait nodes to avoid 429 errors. When the service receives too many requests, implement
+batching to reduce request frequency or use the "Retry on Fail" feature.
+
+Memory Issues: Avoid processing very large datasets in a single run; use batching and increase server resources if
+needed. Use Split In Batches node to process 200 rows at a time, leverage built-in nodes instead of custom code, and
+increase execution timeouts via environment variables.
+
+Empty or Unexpected Data: Some sites use JavaScript to render content, which may not be accessible via simple HTTP
+requests. Standard HTTP and HTML parsing nodes fail because sites load data asynchronously via JavaScript, leaving the
+initial HTML empty of actual content. Web scraping nodes can be used to avoid this.
+`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.ScrapingAndResearchBestPractices = ScrapingAndResearchBestPractices;
+//# sourceMappingURL=scraping-and-research.js.map

package/dist/tools/best-practices/scraping-and-research.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scraping-and-research.js","sourceRoot":"","sources":["../../../src/tools/best-practices/scraping-and-research.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,gCAAgC;IACnC,SAAS,GAAG,kCAAiB,CAAC,qBAAqB,CAAC;IACpD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqIjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA9ID,4EA8IC"}

package/dist/tools/builder-tools.js

@@ -3,7 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getBuilderTools = getBuilderTools;
 exports.getBuilderToolsForDisplay = getBuilderToolsForDisplay;
 const add_node_tool_1 = require("./add-node.tool");
+const categorize_prompt_tool_1 = require("./categorize-prompt.tool");
 const connect_nodes_tool_1 = require("./connect-nodes.tool");
+const get_best_practices_tool_1 = require("./get-best-practices.tool");
 const get_node_parameter_tool_1 = require("./get-node-parameter.tool");
 const node_details_tool_1 = require("./node-details.tool");
 const node_search_tool_1 = require("./node-search.tool");
@@ -13,6 +15,8 @@ const update_node_parameters_tool_1 = require("./update-node-parameters.tool");
 const validate_workflow_tool_1 = require("./validate-workflow.tool");
 function getBuilderTools({ parsedNodeTypes, logger, llmComplexTask, instanceUrl, }) {
     return [
+        (0, categorize_prompt_tool_1.createCategorizePromptTool)(llmComplexTask, logger),
+        (0, get_best_practices_tool_1.createGetBestPracticesTool)(),
         (0, node_search_tool_1.createNodeSearchTool)(parsedNodeTypes),
         (0, node_details_tool_1.createNodeDetailsTool)(parsedNodeTypes),
         (0, add_node_tool_1.createAddNodeTool)(parsedNodeTypes),
@@ -26,6 +30,8 @@ function getBuilderTools({ parsedNodeTypes, logger, llmComplexTask, instanceUrl,
 }
 function getBuilderToolsForDisplay({ nodeTypes, }) {
     return [
+        categorize_prompt_tool_1.CATEGORIZE_PROMPT_TOOL,
+        get_best_practices_tool_1.GET_BEST_PRACTICES_TOOL,
         node_search_tool_1.NODE_SEARCH_TOOL,
         node_details_tool_1.NODE_DETAILS_TOOL,
         (0, add_node_tool_1.getAddNodeToolBase)(nodeTypes),

package/dist/tools/builder-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"builder-tools.js","sourceRoot":"","sources":["../../src/tools/builder-tools.ts"],"names":[],"mappings":";;AAmBA,0CAsBC;AAOD,8DAcC;AAxDD,mDAAwE;AACxE,6DAAkF;AAClF,uEAAgG;AAChG,2DAA+E;AAC/E,yDAA4E;AAC5E,qEAA8F;AAC9F,yDAA4E;AAC5E,+EAGuC;AACvC,qEAA8F;AAE9F,SAAgB,eAAe,CAAC,EAC/B,eAAe,EACf,MAAM,EACN,cAAc,EACd,WAAW,GAMX;IACA,OAAO;QACN,IAAA,uCAAoB,EAAC,eAAe,CAAC;QACrC,IAAA,yCAAqB,EAAC,eAAe,CAAC;QACtC,IAAA,iCAAiB,EAAC,eAAe,CAAC;QAClC,IAAA,2CAAsB,EAAC,eAAe,EAAE,MAAM,CAAC;QAC/C,IAAA,mDAA0B,EAAC,MAAM,CAAC;QAClC,IAAA,uCAAoB,EAAC,MAAM,CAAC;QAC5B,IAAA,4DAA8B,EAAC,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,CAAC;QACpF,IAAA,oDAA0B,GAAE;QAC5B,IAAA,mDAA0B,EAAC,eAAe,EAAE,MAAM,CAAC;KACnD,CAAC;AACH,CAAC;AAOD,SAAgB,yBAAyB,CAAC,EACzC,SAAS,GAC8B;IACvC,OAAO;QACN,mCAAgB;QAChB,qCAAiB;QACjB,IAAA,kCAAkB,EAAC,SAAS,CAAC;QAC7B,uCAAkB;QAClB,+CAAsB;QACtB,mCAAgB;QAChB,0DAA4B;QAC5B,iDAAuB;QACvB,+CAAsB;KACtB,CAAC;AACH,CAAC"}
+{"version":3,"file":"builder-tools.js","sourceRoot":"","sources":["../../src/tools/builder-tools.ts"],"names":[],"mappings":";;AAqBA,0CAwBC;AAOD,8DAgBC;AA9DD,mDAAwE;AACxE,qEAA8F;AAC9F,6DAAkF;AAClF,uEAAgG;AAChG,uEAAgG;AAChG,2DAA+E;AAC/E,yDAA4E;AAC5E,qEAA8F;AAC9F,yDAA4E;AAC5E,+EAGuC;AACvC,qEAA8F;AAE9F,SAAgB,eAAe,CAAC,EAC/B,eAAe,EACf,MAAM,EACN,cAAc,EACd,WAAW,GAMX;IACA,OAAO;QACN,IAAA,mDAA0B,EAAC,cAAc,EAAE,MAAM,CAAC;QAClD,IAAA,oDAA0B,GAAE;QAC5B,IAAA,uCAAoB,EAAC,eAAe,CAAC;QACrC,IAAA,yCAAqB,EAAC,eAAe,CAAC;QACtC,IAAA,iCAAiB,EAAC,eAAe,CAAC;QAClC,IAAA,2CAAsB,EAAC,eAAe,EAAE,MAAM,CAAC;QAC/C,IAAA,mDAA0B,EAAC,MAAM,CAAC;QAClC,IAAA,uCAAoB,EAAC,MAAM,CAAC;QAC5B,IAAA,4DAA8B,EAAC,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,CAAC;QACpF,IAAA,oDAA0B,GAAE;QAC5B,IAAA,mDAA0B,EAAC,eAAe,EAAE,MAAM,CAAC;KACnD,CAAC;AACH,CAAC;AAOD,SAAgB,yBAAyB,CAAC,EACzC,SAAS,GAC8B;IACvC,OAAO;QACN,+CAAsB;QACtB,iDAAuB;QACvB,mCAAgB;QAChB,qCAAiB;QACjB,IAAA,kCAAkB,EAAC,SAAS,CAAC;QAC7B,uCAAkB;QAClB,+CAAsB;QACtB,mCAAgB;QAChB,0DAA4B;QAC5B,iDAAuB;QACvB,+CAAsB;KACtB,CAAC;AACH,CAAC"}

package/dist/tools/categorize-prompt.tool.d.ts

@@ -0,0 +1,5 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { Logger } from '@n8n/backend-common';
+import type { BuilderTool, BuilderToolBase } from '../utils/stream-processor';
+export declare const CATEGORIZE_PROMPT_TOOL: BuilderToolBase;
+export declare function createCategorizePromptTool(llm: BaseChatModel, logger?: Logger): BuilderTool;

package/dist/tools/categorize-prompt.tool.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CATEGORIZE_PROMPT_TOOL = void 0;
+exports.createCategorizePromptTool = createCategorizePromptTool;
+const tools_1 = require("@langchain/core/tools");
+const zod_1 = require("zod");
+const prompt_categorization_1 = require("../chains/prompt-categorization");
+const errors_1 = require("../errors");
+const progress_1 = require("../tools/helpers/progress");
+const response_1 = require("../tools/helpers/response");
+const categorizePromptSchema = zod_1.z.object({
+    prompt: zod_1.z.string().min(1).describe('The user prompt to categorize'),
+});
+function buildCategorizationMessage(categorization) {
+    const parts = [];
+    parts.push('Prompt categorized');
+    if (categorization.techniques.length > 0) {
+        parts.push(`- Techniques: ${categorization.techniques.join(', ')}`);
+    }
+    if (categorization.confidence !== undefined) {
+        parts.push(`- Confidence: ${(categorization.confidence * 100).toFixed(0)}%`);
+    }
+    return parts.join('\n');
+}
+exports.CATEGORIZE_PROMPT_TOOL = {
+    toolName: 'categorize_prompt',
+    displayTitle: 'Categorizing prompt',
+};
+function createCategorizePromptTool(llm, logger) {
+    const dynamicTool = (0, tools_1.tool)(async (input, config) => {
+        const reporter = (0, progress_1.createProgressReporter)(config, exports.CATEGORIZE_PROMPT_TOOL.toolName, exports.CATEGORIZE_PROMPT_TOOL.displayTitle);
+        try {
+            const validatedInput = categorizePromptSchema.parse(input);
+            const { prompt } = validatedInput;
+            reporter.start(validatedInput);
+            logger?.debug('Categorizing user prompt using LLM...');
+            reporter.progress('Analyzing prompt to identify use case and techniques...');
+            const categorization = await (0, prompt_categorization_1.promptCategorizationChain)(llm, prompt);
+            logger?.debug('Prompt categorized', {
+                techniques: categorization.techniques,
+                confidence: categorization.confidence,
+            });
+            const output = {
+                categorization,
+            };
+            reporter.complete(output);
+            return (0, response_1.createSuccessResponse)(config, buildCategorizationMessage(categorization), {
+                categorization,
+            });
+        }
+        catch (error) {
+            if (error instanceof zod_1.z.ZodError) {
+                const validationError = new errors_1.ValidationError('Invalid input parameters', {
+                    extra: { errors: error.errors },
+                });
+                reporter.error(validationError);
+                return (0, response_1.createErrorResponse)(config, validationError);
+            }
+            const toolError = new errors_1.ToolExecutionError(error instanceof Error ? error.message : 'Unknown error occurred', {
+                toolName: exports.CATEGORIZE_PROMPT_TOOL.toolName,
+                cause: error instanceof Error ? error : undefined,
+            });
+            reporter.error(toolError);
+            return (0, response_1.createErrorResponse)(config, toolError);
+        }
+    }, {
+        name: exports.CATEGORIZE_PROMPT_TOOL.toolName,
+        description: `Categorize a user's workflow request to identify the use case and required techniques.
+
+This helps understand what type of workflow the user wants to build and which automation patterns will be needed.
+
+Use this tool when you receive an initial workflow request to:
+- Detect required techniques (e.g., scraping, data transformation, notifications)
+- Better understand the user's needs and context
+
+The categorization allows retrieving relevant best practice documentation to improve workflow structure and node selection.`,
+        schema: categorizePromptSchema,
+    });
+    return {
+        tool: dynamicTool,
+        ...exports.CATEGORIZE_PROMPT_TOOL,
+    };
+}
+//# sourceMappingURL=categorize-prompt.tool.js.map

package/dist/tools/categorize-prompt.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"categorize-prompt.tool.js","sourceRoot":"","sources":["../../src/tools/categorize-prompt.tool.ts"],"names":[],"mappings":"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"}

package/dist/tools/engines/node-search-engine.d.ts

@@ -1,12 +1,6 @@
 import type { INodeTypeDescription, NodeConnectionType } from 'n8n-workflow';
 import type { NodeSearchResult } from '../../types/nodes';
 export declare const SCORE_WEIGHTS: {
-    readonly NAME_CONTAINS: 10;
-    readonly DISPLAY_NAME_CONTAINS: 8;
-    readonly DESCRIPTION_CONTAINS: 5;
-    readonly ALIAS_CONTAINS: 8;
-    readonly NAME_EXACT: 20;
-    readonly DISPLAY_NAME_EXACT: 15;
     readonly CONNECTION_EXACT: 100;
     readonly CONNECTION_IN_EXPRESSION: 50;
 };
@@ -16,10 +10,7 @@ export declare class NodeSearchEngine {
     searchByName(query: string, limit?: number): NodeSearchResult[];
     searchByConnectionType(connectionType: NodeConnectionType, limit?: number, nameFilter?: string): NodeSearchResult[];
     formatResult(result: NodeSearchResult): string;
-    private calculateNameScore;
     private getConnectionScore;
-    private createSearchResult;
-    private sortAndLimit;
     static isAiConnectionType(connectionType: string): boolean;
     static getAiConnectionTypes(): NodeConnectionType[];
 }