@n8n/ai-workflow-builder 0.31.1 → 0.32.0

package/dist/tools/best-practices/human-in-the-loop.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HumanInTheLoopBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class HumanInTheLoopBestPractices {
+    technique = categorization_1.WorkflowTechnique.HUMAN_IN_THE_LOOP;
+    version = '1.0.0';
+    documentation = `# Best Practices: Human-in-the-Loop Workflows
+
+## Workflow Design
+
+Structure workflows in three stages: Automation → Human Decision → Resume Processing. The Wait node is the core component for implementing pauses.
+
+Break the workflow into clear stages:
+1. **Initial Automation**: Execute automated steps leading to the decision point (data extraction, AI content generation, etc.)
+2. **Human Notification**: Send notification with resume URL via preferred channel (Email, Slack, Telegram)
+3. **Wait for Response**: Configure Wait node with appropriate resume condition
+4. **Process Decision**: Use IF/Switch nodes to branch based on human input
+
+Example pattern:
+- Trigger → Generate Content → Email (with resume URLs) → Wait Node → IF (decision) → Publish/Reject
+- HTTP Request (fetch data) → Filter → Email Manager → Wait (On Webhook) → Switch (approval status) → Database Update
+
+CRITICAL: Always include the $execution.resumeUrl in notification messages. This unique URL resumes the specific workflow execution when accessed.
+
+## Wait Node Configuration
+
+The Wait node supports four resume conditions:
+- **After Time Interval**: Resume after fixed delay (not for human decisions)
+- **At Specified Time**: Resume at specific date/time (not for human decisions)
+- **On Webhook Call**: Resume when URL is accessed (ideal for link-based approvals)
+- **On Form Submitted**: Resume when user submits n8n-hosted form (best for structured input)
+
+For human-in-the-loop, use "On Webhook Call" or "On Form Submitted" modes.
+
+### Webhook Configuration
+- Set HTTP method (GET for simple links, POST for data)
+- Configure authentication if needed (None for private URLs, Basic/Token for security)
+- Enable "Ignore Bots" to prevent email scanners/chat bots from triggering
+- Use Webhook Suffix for multiple wait points in same workflow
+
+### Form Configuration
+- Design form fields directly in Wait node
+- Specify field types, labels, validation
+- Form automatically hosts at resume URL
+- Submitted data merges with workflow context
+
+## Timeout Management
+
+Always configure "Limit Wait Time" to prevent infinite waits:
+- Set maximum wait duration (e.g., 48 hours)
+- Or specify absolute deadline date
+- Handle timeout case in workflow logic
+- Check if resumed by timeout (no webhook/form data present)
+
+## Communication Patterns
+
+### Direct Link Method
+Include $execution.resumeUrl directly in messages:
+
+Email: Click to [Approve]({{$execution.resumeUrl}}?decision=approve) or [Reject]({{$execution.resumeUrl}}?decision=reject)
+Slack: Please review and click: {{$execution.resumeUrl}}
+
+### Platform Response Method
+For responses within platform (Slack reply, email response):
+- Use separate trigger workflow to catch responses
+- Correlate to correct execution via ID
+- Call resume URL programmatically
+- More complex but keeps interaction native
+
+## Data Handling
+
+The Wait node preserves all prior workflow data when resuming:
+- Original context remains available
+- New input data (form/webhook) adds to context
+- Access webhook data via $json after Wait node
+- Query parameters available in $json.query
+- Form fields merge directly into JSON output
+
+## Recommended Nodes
+
+### Wait (n8n-nodes-base.wait)
+
+**Purpose**: Core node for pausing workflow execution until human input
+
+**Key Settings**:
+- Resume: "On Webhook Call" or "On Form Submitted"
+- Authentication: Configure based on security needs
+- Ignore Bots: Enable to prevent accidental triggers
+- Limit Wait Time: Set timeout to prevent infinite waits
+
+**Use Cases**:
+- Approval workflows
+- Data collection from humans
+- Multi-step verification processes
+
+**Best Practices**:
+- Always include timeout handling
+- Use unique webhook suffixes for multiple waits
+- Test resume URLs during development
+
+### Email (n8n-nodes-base.emailSend)
+
+**Purpose**: Send notifications with resume links to users
+
+**Use Cases**:
+- Approval request emails
+- Data verification requests
+- Task assignment notifications
+
+**Best Practices**:
+- Include clear call-to-action buttons
+- Embed resume URL as hyperlinks
+- Provide context about the decision needed
+
+### Slack (n8n-nodes-base.slack)
+
+**Purpose**: Send notifications via Slack with resume links
+
+**Best Practices**:
+- Wrap URLs in <> to prevent unfurling
+- Use clear message formatting
+- Consider using blocks for rich formatting
+
+### Telegram (n8n-nodes-base.telegram)
+
+**Purpose**: Send notifications via Telegram
+
+**Best Practices**:
+- Enable "Ignore Bots" in Wait node
+- Use inline keyboards for better UX
+- Keep messages concise
+
+### IF (n8n-nodes-base.if)
+
+**Purpose**: Branch workflow based on human decision
+
+**Use Cases**:
+- Route approved vs rejected items
+- Check if response was received (vs timeout)
+- Validate input data
+
+**Best Practices**:
+- Handle all possible decision values
+- Include default/timeout branch
+- Use clear condition names
+
+### Switch (n8n-nodes-base.switch)
+
+**Purpose**: Multi-way branching for complex decisions
+
+**Use Cases**:
+- Multiple approval levels
+- Various response options
+- Status-based routing
+
+### HTTP Request (n8n-nodes-base.httpRequest)
+
+**Purpose**: Call external APIs after human decision
+
+**Use Cases**:
+- Update external systems
+- Trigger downstream processes
+- Log decisions to external services
+
+### Database Nodes
+
+**MySQL** (n8n-nodes-base.mySql), **Postgres** (n8n-nodes-base.postgres), **MongoDB** (n8n-nodes-base.mongoDb):
+- Store approval history
+- Update record status after decision
+- Log human inputs for audit
+
+### Google Sheets (n8n-nodes-base.googleSheets)
+
+**Purpose**: Track decisions and maintain approval logs
+
+**Use Cases**:
+- Approval tracking spreadsheets
+- Decision audit logs
+- User response collection
+
+## Common Pitfalls to Avoid
+
+### Accidental Resume Triggers
+
+**Problem**: Email clients or chat apps preview links and trigger resume unintentionally.
+
+**Solution**:
+- Enable "Ignore Bots" option in Wait node
+- Wrap Slack URLs in <> to prevent unfurling
+- Use authentication for sensitive workflows
+- Educate users to click only when ready
+
+### Missing Timeouts
+
+**Problem**: Workflow waits forever if human never responds.
+
+**Solution**:
+- Always set "Limit Wait Time" (e.g., 3 days)
+- Handle timeout scenario in workflow logic
+- Send reminder before deadline
+- Escalate to another person if timeout occurs
+
+### Lost Context After Wait
+
+**Problem**: Assuming data is lost after Wait node resumes.
+
+**Solution**:
+- Wait node preserves all prior data automatically
+- New input merges with existing context
+- Test data structure after resume
+- Use expressions to access both old and new data
+
+### Security Issues with Resume URLs
+
+**Problem**: Resume URLs exposed to unauthorized users.
+
+**Solution**:
+- Treat resume URLs as secrets
+- Use authentication options for sensitive workflows
+- Send only through private channels
+- Consider IP whitelisting if needed
+
+### Multiple Wait Node Confusion
+
+**Problem**: Using same webhook URL for different wait points.
+
+**Solution**:
+- Use unique Webhook Suffix for each Wait node
+- Generate fresh $execution.resumeUrl for each wait
+- Label wait points clearly
+- Document which URL corresponds to which decision
+
+### Not Handling All Response Types
+
+**Problem**: Only handling expected responses, not edge cases.
+
+**Solution**:
+- Handle timeout case explicitly
+- Provide default action for unexpected inputs
+- Validate form data before processing
+- Log all decisions for debugging
+
+### Workflow State Persistence
+
+**Problem**: Worrying about resource consumption during wait.
+
+**Solution**:
+- Waiting executions are saved to database, not running
+- No worker threads consumed during wait
+- Can have hundreds of paused workflows
+- Survives n8n restarts (state in database)
+
+### Complex Parallel Approvals
+
+**Problem**: Need multiple people to approve before continuing.
+
+**Solution**:
+- Use separate Wait node per approver
+- Or create sub-workflow per approver
+- Use Merge node to synchronize branches
+- Consider approval tracking in database`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.HumanInTheLoopBestPractices = HumanInTheLoopBestPractices;
+//# sourceMappingURL=human-in-the-loop.js.map

package/dist/tools/best-practices/human-in-the-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-in-the-loop.js","sourceRoot":"","sources":["../../../src/tools/best-practices/human-in-the-loop.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,2BAA2B;IAC9B,SAAS,GAAG,kCAAiB,CAAC,iBAAiB,CAAC;IAChD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yCA8PO,CAAC;IAEzC,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAvQD,kEAuQC"}

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

@@ -5,23 +5,24 @@ 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 document_processing_1 = require("./document-processing");
 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_EXTRACTION]: new data_extraction_1.DataExtractionBestPractices(),
     [categorization_1.WorkflowTechnique.DATA_TRANSFORMATION]: undefined,
-    [categorization_1.WorkflowTechnique.DOCUMENT_PROCESSING]: undefined,
+    [categorization_1.WorkflowTechnique.DOCUMENT_PROCESSING]: new document_processing_1.DocumentProcessingBestPractices(),
     [categorization_1.WorkflowTechnique.ENRICHMENT]: undefined,
-    [categorization_1.WorkflowTechnique.HUMAN_IN_THE_LOOP]: undefined,
+    [categorization_1.WorkflowTechnique.FORM_INPUT]: new form_input_1.FormInputBestPractices(),
     [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,
+    [categorization_1.WorkflowTechnique.HUMAN_IN_THE_LOOP]: undefined,
+    [categorization_1.WorkflowTechnique.MONITORING]: undefined,
+    [categorization_1.WorkflowTechnique.SCHEDULING]: undefined,
 };
 //# sourceMappingURL=index.js.map

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

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/best-practices/index.ts"],"names":[],"mappings":";;;AACA,2DAAuF;AAEvF,uCAAiD;AACjD,6DAAsE;AAEtE,uDAAgE;AAEhE,+DAAwE;AAExE,6CAAsD;AAKtD,mEAA2E;AAI9D,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,aAAa,CAAC,EAAE,SAAS;IAC5C,CAAC,kCAAiB,CAAC,eAAe,CAAC,EAAE,IAAI,6CAA2B,EAAE;IACtE,CAAC,kCAAiB,CAAC,mBAAmB,CAAC,EAAE,SAAS;IAClD,CAAC,kCAAiB,CAAC,mBAAmB,CAAC,EAAE,IAAI,qDAA+B,EAAE;IAC9E,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;IACzC,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,IAAI,mCAAsB,EAAE;IAC5D,CAAC,kCAAiB,CAAC,cAAc,CAAC,EAAE,SAAS;IAC7C,CAAC,kCAAiB,CAAC,YAAY,CAAC,EAAE,SAAS;IAC3C,CAAC,kCAAiB,CAAC,MAAM,CAAC,EAAE,SAAS;IACrC,CAAC,kCAAiB,CAAC,iBAAiB,CAAC,EAAE,SAAS;IAChD,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;IACzC,CAAC,kCAAiB,CAAC,UAAU,CAAC,EAAE,SAAS;CACzC,CAAC"}

package/dist/tools/best-practices/knowledge-base.d.ts

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

package/dist/tools/best-practices/knowledge-base.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeBaseBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class KnowledgeBaseBestPractices {
+    technique = categorization_1.WorkflowTechnique.KNOWLEDGE_BASE;
+    version = '1.0.0';
+    documentation = `# Best Practices: Knowledge Base Workflows
+
+## Workflow Design
+
+### Architecture Pattern
+- **Separate Workflows**: Split into two distinct parts:
+  - **Ingestion Workflow**: Processes and indexes documents into vector database (triggered on new content or schedule)
+  - **Query Workflow**: Retrieves relevant information and generates answers (triggered by user queries)
+- **Modular Design**: Use Execute Workflow node to call query workflow from multiple channels (chat, API, Slack, etc.)
+
+### Trigger Strategy
+- **Ingestion Triggers**: File Watchers (Google Drive, S3), Schedule triggers for periodic re-indexing
+- **Query Triggers**: Chat Trigger, Webhook, Slack Trigger based on input channel
+
+### Data Type Handling
+- Use Switch/If nodes or Code node to route different file types to appropriate extraction branches
+- Separate processing paths for PDFs, databases, web pages, etc.
+
+## Core Processing Pipeline
+
+### Document Processing
+1. **Fetch Documents**: Google Drive/Dropbox/S3 nodes, HTTP Request node, Database nodes
+2. **Load & Split**: Default Data Loader → Recursive Character Text Splitter
+   - Chunk size: 500-1000 characters (~200 tokens)
+   - Overlap: 10-15% to preserve context
+3. **Generate Embeddings**: Embeddings node (OpenAI/HuggingFace/Cohere)
+   - **Critical**: Use same model for indexing and queries
+   - Example: text-embedding-ada-002 (1536 dimensions)
+
+### Vector Store Configuration
+- **Insert Mode**:
+  - Use upsert with unique IDs (document ID + chunk number)
+  - Include metadata (source, title, page number)
+  - Clear namespace option for complete replacement
+- **Query Mode**:
+  - Top-K limit: 3-5 results typically optimal
+  - Apply similarity score threshold to filter irrelevant matches
+
+### LLM Integration
+- **Agent Approach**: AI Agent node with Vector Store Tool
+  - Configure clear tool description: "Company Knowledge Base – use this to find relevant policy documents"
+  - Connect Window Buffer Memory for conversation history
+- **Direct Query**: Vector Store (Get Many) → OpenAI Chat Model with crafted prompt
+- **System Prompt**: "Answer using only the information from our knowledge base. If you don't find an answer in the provided documents, say you don't know."
+- **Temperature**: 0-0.3 for factual accuracy
+
+## Recommended Nodes
+
+### Document Handling
+
+**Google Drive** (n8n-nodes-base.googleDrive):
+- Purpose: File triggers and retrieval from Google Drive
+- Use cases: Monitor folders for new documents, fetch specific files
+- Best practices: Use triggers for automatic ingestion, handle file types appropriately
+
+**HTTP Request** (n8n-nodes-base.httpRequest):
+- Purpose: Fetch documents from URLs/APIs
+- Use cases: Pull content from web pages, download files from APIs
+- Best practices: Handle authentication, check response formats
+
+**Notion** (n8n-nodes-base.notion):
+- Purpose: Retrieve content from Notion databases and pages
+- Use cases: Index company wikis, documentation in Notion
+- Best practices: Use appropriate API version, handle nested content
+
+**Postgres** (n8n-nodes-base.postgres):
+- Purpose: Query database content for indexing
+- Use cases: Index structured data, retrieve records for embedding
+- Best practices: Use efficient queries, batch large datasets
+
+### AI Processing Chain
+
+**Document Default Data Loader** (@n8n/n8n-nodes-langchain.documentDefaultDataLoader):
+- Purpose: Load documents into LangChain format
+- Use cases: Initial document processing, format conversion
+- Best practices: Handle various document types, preserve metadata
+
+**Text Splitter Recursive Character** (@n8n/n8n-nodes-langchain.textSplitterRecursiveCharacterTextSplitter):
+- Purpose: Split documents into manageable chunks
+- Configuration:
+  - Chunk size: 500-1000 characters (~200 tokens)
+  - Overlap: 10-15% to preserve context
+- Best practices: Test chunk sizes for optimal retrieval quality, ensure context preservation
+
+**Embeddings OpenAI** (@n8n/n8n-nodes-langchain.embeddingsOpenAi):
+- Purpose: Generate vector embeddings for text
+- Model options:
+  - text-embedding-3-small (newer, cost-effective)
+  - text-embedding-ada-002 (1536 dimensions, widely used)
+- **Critical**: Use same model for indexing and queries
+- Best practices: Choose model based on quality/cost tradeoffs, maintain consistency
+
+### Vector Stores
+
+**Vector Store Pinecone** (@n8n/n8n-nodes-langchain.vectorStorePinecone):
+- Purpose: Pinecone vector database integration
+- Use cases: Production knowledge bases, scalable deployments
+- Best practices: Use namespaces for organization, set appropriate index dimensions
+
+**Vector Store Qdrant** (@n8n/n8n-nodes-langchain.vectorStoreQdrant):
+- Purpose: Qdrant vector database integration
+- Use cases: Self-hosted vector storage, high-performance search
+- Best practices: Configure collections properly, use filters for metadata
+
+**Vector Store Supabase** (@n8n/n8n-nodes-langchain.vectorStoreSupabase):
+- Purpose: Supabase pgvector integration
+- Use cases: PostgreSQL-based vector storage, integrated with existing Supabase projects
+- Best practices: Ensure pgvector extension is enabled, use proper indexing
+
+**Vector Store In Memory** (@n8n/n8n-nodes-langchain.vectorStoreInMemory):
+- Purpose: In-memory vector storage for testing
+- Use cases: Development, testing, small datasets
+- Best practices: Not for production, data lost on restart
+
+### Agent & LLM
+
+**AI Agent** (@n8n/n8n-nodes-langchain.agent):
+- Purpose: Orchestrate tool use and LLM interactions
+- Configuration: Connect Vector Store Tool, add memory
+- Best practices: Configure clear tool descriptions, use appropriate prompts
+
+**Tool Vector Store** (@n8n/n8n-nodes-langchain.toolVectorStore):
+- Purpose: Vector store tool for agents
+- Configuration: "Company Knowledge Base – use this to find relevant policy documents"
+- Best practices: Use descriptive tool names, set appropriate retrieval limits (3-5 results)
+
+**OpenAI** (@n8n/n8n-nodes-langchain.openAi):
+- Purpose: Chat model for generating responses
+- Configuration:
+  - Temperature: 0-0.3 for factual Q&A
+  - System prompt: "Answer using only the information from our knowledge base"
+- Best practices: Use low temperature for accuracy, instruct to admit when unsure
+
+**Memory Window Buffer** (@n8n/n8n-nodes-langchain.memoryBufferWindow):
+- Purpose: Maintain conversation history
+- Configuration: 3-5 message turns typically sufficient
+- Best practices: Balance context preservation with token limits
+
+### Utility
+
+**Switch** (n8n-nodes-base.switch):
+- Purpose: Route by file type or content type
+- Use cases: Different processing for PDFs vs text vs images
+- Best practices: Always define default case, use clear conditions
+
+**Execute Workflow** (n8n-nodes-base.executeWorkflow):
+- Purpose: Call sub-workflows for modular design
+- Use cases: Reuse query workflow across channels, separate ingestion logic
+- Best practices: Design for reusability, pass appropriate parameters
+
+## Common Pitfalls to Avoid
+
+### Critical Mistakes
+
+**Inconsistent Embeddings**:
+- **Problem**: Using different embedding models for indexing vs queries breaks semantic search
+- **Solution**: Always use the same model throughout (e.g., text-embedding-ada-002 for both)
+- Document which model is used in workflow description
+
+**Vector Dimension Mismatch**:
+- **Problem**: Index dimensions don't match embedding model output, causing errors
+- **Solution**: Ensure vector store index dimensions match embedding model output exactly
+- Common: ada-002 = 1536 dimensions, text-embedding-3-small = 1536 dimensions
+
+**Missing Updates**:
+- **Problem**: Not updating or removing outdated vectors leads to conflicting information
+- **Solution**: Implement update/delete mechanisms with unique IDs
+- Use document ID + chunk number as unique identifier
+- Schedule regular re-indexing for changing content
+
+**Treating Vector DB as Full Database**:
+- **Problem**: Using vector stores for general data storage instead of semantic search
+- **Solution**: Vector DBs are for semantic search only, not bulk data storage
+- Store full documents in traditional databases, only embeddings in vector store
+
+### Performance Issues
+
+**Oversized Chunks**:
+- **Problem**: Large chunks dilute relevance and exceed token limits
+- **Solution**: Keep chunks to 500-1000 characters (~200 tokens)
+- Test different sizes to find optimal retrieval quality
+
+**Undersized Chunks**:
+- **Problem**: Too small chunks lose necessary context
+- **Solution**: Ensure chunks have sufficient context to be meaningful
+- Use 10-15% overlap between chunks
+
+**Too Many Retrieved Documents**:
+- **Problem**: Retrieving 10+ documents overwhelms LLM and reduces accuracy
+- **Solution**: Limit to 3-5 results for optimal quality
+- Use similarity thresholds to filter irrelevant matches
+
+**UI Overload**:
+- **Problem**: Indexing thousands of chunks freezes workflow editor
+- **Solution**: Run large indexing jobs in production mode, not editor
+- Consider batch processing for very large datasets
+
+### Configuration Errors
+
+**No Metadata**:
+- **Problem**: Missing source/date metadata makes results less interpretable
+- **Solution**: Always include metadata (source, title, page number, date)
+- Helps users understand context of retrieved information
+
+**No Unique IDs**:
+- **Problem**: Can't update specific documents, causes duplicates
+- **Solution**: Use document ID + chunk number as unique identifier
+- Enables targeted updates and deletions
+
+**High Temperature**:
+- **Problem**: Creative temperature settings cause hallucinations in factual Q&A
+- **Solution**: Use temperature 0-0.3 for factual responses
+- Higher temperatures (0.7-1.0) only for creative tasks
+
+**Generic Tool Descriptions**:
+- **Problem**: Vague descriptions cause agents to misuse tools
+- **Solution**: Use specific, descriptive tool names
+- Good: "Company HR Policy Knowledge Base"
+- Bad: "Knowledge base"
+
+### Data Management
+
+**Stale Data**:
+- **Problem**: Outdated information in knowledge base leads to wrong answers
+- **Solution**: Schedule regular re-indexing or implement change detection
+- Use document timestamps to track freshness
+
+**No Namespace Separation**:
+- **Problem**: Mixing unrelated domains in same index reduces accuracy
+- **Solution**: Use namespaces to separate different knowledge domains
+- Example: "hr-policies", "technical-docs", "customer-faqs"
+
+**Ignoring Token Limits**:
+- **Problem**: Combined length of query + context + response exceeds model limits
+- **Solution**: Monitor total token usage, limit context appropriately
+- GPT-4: 8k/32k tokens, GPT-3.5: 4k/16k tokens
+
+**Security Gaps**:
+- **Problem**: Sending sensitive data without access control or encryption
+- **Solution**: Implement proper access controls, use secure connections
+- Consider data classification and access restrictions
+
+## Best Practices Summary
+
+1. **Always use consistent embedding models** throughout the pipeline
+2. **Design modular workflows** for reusability across channels
+3. **Include metadata** for better context and filtering
+4. **Implement proper update/delete mechanisms** with unique IDs
+5. **Test chunk sizes** for optimal retrieval quality (500-1000 characters)
+6. **Run large indexing operations** in production mode
+7. **Set appropriate retrieval limits** (3-5 results) and similarity thresholds
+8. **Use low temperature** (0-0.3) for factual responses
+9. **Secure sensitive data** with proper access controls
+10. **Monitor and update** regularly to prevent stale information
+`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.KnowledgeBaseBestPractices = KnowledgeBaseBestPractices;
+//# sourceMappingURL=knowledge-base.js.map

package/dist/tools/best-practices/knowledge-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-base.js","sourceRoot":"","sources":["../../../src/tools/best-practices/knowledge-base.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,0BAA0B;IAC7B,SAAS,GAAG,kCAAiB,CAAC,cAAc,CAAC;IAC7C,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8PjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAvQD,gEAuQC"}

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

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