@atom8n/ai-workflow-builder 1.2.0

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;
+}

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

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MonitoringBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class MonitoringBestPractices {
+    technique = categorization_1.WorkflowTechnique.MONITORING;
+    version = '1.0.0';
+    documentation = `# Best Practices: Monitoring Workflows
+
+## Workflow Design
+
+Structure monitoring workflows with a Schedule Trigger for periodic checks, HTTP Request or appropriate check nodes for service status, and IF/Switch nodes for conditional alerting. Always enable error handling to prevent workflow crashes when services are down.
+
+CRITICAL: Enable "Continue On Fail" or "Never Error" mode on check nodes - otherwise the workflow stops exactly when you need alerts. This is the most common monitoring mistake.
+
+Example pattern for website monitoring:
+- Schedule Trigger (every 5 minutes) → HTTP Request (check status) → IF (status != 200?) → Send alert
+- Always test both success and failure paths during development
+
+For monitoring multiple services, store URLs/endpoints in Google Sheets or databases and loop through them rather than duplicating workflows.
+
+## Scheduling & Activation
+
+Always activate the workflow after configuration - forgetting this means no monitoring occurs. Test schedules with manual execution before relying on them in production.
+
+Configure appropriate check intervals based on criticality:
+- Critical services: 1-5 minutes
+- Important services: 10-15 minutes
+- Non-critical: 30-60 minutes
+
+Set correct time zones in Workflow Settings for daily/weekly schedules. Use crontab.guru to verify complex Cron expressions.
+
+## Service Status Checking
+
+Configure HTTP Request nodes with:
+- Timeout: Set to a few seconds to prevent hanging
+- Include Headers & Status: Access response codes for condition evaluation
+- Retry on Fail: 2-3 retries with 1s delay to filter transient failures
+- Authentication: Use credential system, never hardcode secrets
+
+For non-HTTP monitoring:
+- Databases: Use Query nodes (MySQL, Postgres) for health checks
+- Systems: Execute Command node for ping or custom scripts
+- APIs: Check specific endpoints, not just base URLs
+
+## Alert Configuration
+
+Implement multi-channel alerting for critical services to ensure visibility. Configure notifications with useful context.
+
+Message content should include:
+- Service name/URL
+- Failure time: {{$now}}
+- Error details: {{$json["statusCode"]}}
+- Example: "⚠️ Website XYZ DOWN (status 500) at {{new Date().toISOString()}}"
+
+Avoid alert storms by:
+- Tracking state changes (only alert when status changes)
+- Throttling repeated alerts (e.g., re-alert after 30 minutes)
+- Storing last known status in Google Sheets or database
+
+## Error Handling & Failsafes
+
+Implement multiple layers of error handling:
+
+1. Node-level: Enable "Continue On Fail" on check nodes
+2. Workflow-level: Create Error Trigger workflow to catch monitoring failures
+3. Heartbeat: Ping external service (healthchecks.io) to verify monitoring is running
+
+Configure Error Workflow in settings to alert when monitoring itself fails - otherwise you have blind spots.
+
+## Logging & State Management
+
+Log check results for trend analysis and uptime calculation. Store in Google Sheets (append row) or database with:
+- Timestamp
+- Service identifier
+- Status (up/down)
+- Response time
+- Error details if applicable
+
+Maintain current status dashboard by updating a status table/sheet that shows at-a-glance health of all monitored services.
+
+## Recommended Nodes
+
+### Schedule Trigger (n8n-nodes-base.scheduleTrigger)
+
+Purpose: Periodic workflow execution at fixed intervals or Cron schedules
+
+Configuration:
+- Set appropriate intervals based on service criticality
+- Always activate the workflow after configuration
+
+### HTTP Request (n8n-nodes-base.httpRequest)
+
+Purpose: Check website/API availability and response codes
+
+Critical settings:
+- Enable "Continue On Fail" to handle errors gracefully
+- Set timeout to prevent hanging (2-5 seconds typical)
+- Configure retries for transient failure filtering
+
+### IF (n8n-nodes-base.if)
+
+Purpose: Evaluate service health and route to appropriate action
+
+Common conditions:
+- {{$json["statusCode"]}} equals 200 (service up)
+- {{$json["statusCode"]}} not equals 200 (service down)
+
+### Send Email (n8n-nodes-base.emailSend)
+
+Purpose: Email alerts for service issues
+
+Configure with SMTP credentials and clear subject lines for quick issue identification.
+
+### Messaging Integration Nodes
+
+- Slack (n8n-nodes-base.slack)
+- Microsoft Teams (n8n-nodes-base.microsoftTeams)
+- Telegram (n8n-nodes-base.telegram)
+- Discord (n8n-nodes-base.discord)
+
+Purpose: Real-time alerts to team communication channels
+
+### Twilio (n8n-nodes-base.twilio)
+
+Purpose: SMS/phone alerts for critical system failures requiring immediate attention
+
+### Database & Storage Nodes
+
+- Google Sheets (n8n-nodes-base.googleSheets)
+- MySQL (n8n-nodes-base.mySql)
+- PostgreSQL (n8n-nodes-base.postgres)
+
+Purpose: Store monitoring configuration, log results, track state changes
+
+### Execute Workflow (n8n-nodes-base.executeWorkflow)
+
+Purpose: Modular monitoring design with sub-workflows for different service types
+
+## Common Pitfalls to Avoid
+
+### Forgetting to Activate Workflow
+
+The #1 monitoring failure - creating the perfect monitoring workflow but forgetting to activate it. Always verify the workflow is active (toggle in top-right of editor).
+
+### No Error Handling on Check Nodes
+
+Without "Continue On Fail", the workflow crashes when services are down - exactly when you need alerts. This makes monitoring useless at the critical moment.
+
+### Alert Storms
+
+Sending alerts every check interval creates fatigue. Implement state tracking to alert only on status changes, not every failed check.
+
+### Incorrect Schedule Configuration
+
+Cron expression mistakes can cause workflows to run at wrong times or not at all. A Cron like "* * * * *" runs every minute (not every hour!). Always test schedules.
+
+### Hardcoded Credentials
+
+Never hardcode API keys, passwords, or sensitive URLs directly in nodes. Use n8n's credential manager for security and maintainability.
+
+### Missing Recovery Notifications
+
+Not sending "service recovered" messages leaves teams uncertain about incident resolution. Track state changes bidirectionally.
+
+### Resource Exhaustion
+
+Monitoring too many services in one workflow or setting intervals too frequent can overload n8n. Split large monitoring lists across multiple workflows.
+
+### No Monitoring of Monitoring
+
+If the monitoring workflow fails, you're blind to service issues. Implement Error Trigger workflows and external heartbeat monitoring for the monitoring system itself.`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.MonitoringBestPractices = MonitoringBestPractices;
+//# sourceMappingURL=monitoring.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"monitoring.js","sourceRoot":"","sources":["../../../src/tools/best-practices/monitoring.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,uBAAuB;IAC1B,SAAS,GAAG,kCAAiB,CAAC,UAAU,CAAC;IACzC,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wKAoKsI,CAAC;IAExK,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA7KD,0DA6KC"}

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

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