NudgeCampaign AI Standards: Conversational Intelligence Best Practices

Generated: 2025-01-29 21:00 UTC
Version: 1.0 - AI-First Development Standards
Scope: AI integration, OpenRouter usage, and conversational intelligence
Purpose: Establish comprehensive standards for AI-driven email marketing platform

---

Document Overview

This document establishes AI-first development standards for NudgeCampaign's conversational intelligence platform. These standards ensure reliable, safe, and cost-effective AI integration across all platform features.

Core AI Principles

• Conversational-First: Every feature accessible through natural language
• Provider-Agnostic: No vendor lock-in, seamless model switching
• Safety-by-Design: Multi-layer validation and human oversight
• Cost-Optimized: Intelligent routing and model selection
• Context-Aware: Rich business and user context in every interaction

AI Stack Overview

Component	Technology	Purpose
Primary Provider	OpenRouter	Multi-model routing and cost optimization
Fallback Providers	OpenAI Direct, Anthropic	Reliability and redundancy
Intent Engine	Custom NLP Pipeline	Business-specific intent classification
Safety Layer	Multi-provider validation	Content safety and compliance
Context Store	Redis + PostgreSQL	Conversation memory and business context

---

Section 1: OpenRouter Integration Standards

Core Architecture with OpenRouter

OpenRouter serves as our primary AI gateway, providing access to multiple models with intelligent routing, cost optimization, and reliability features.

1.1 Provider Configuration

Multi-Provider Setup

interface AIProviderConfig {
  primary: 'openrouter';
  fallback: ['openai', 'anthropic'];
  routing: {
    costOptimized: boolean;
    performanceThreshold: number;
    reliabilityRequirement: number;
  };
}

class OpenRouterProvider implements AIProvider {
  private client: OpenRouter;
  private fallbackProviders: Map<string, AIProvider>;
  
  constructor(config: OpenRouterConfig) {
    this.client = new OpenRouter({
      apiKey: config.apiKey,
      baseURL: 'https://openrouter.ai/api/v1',
      defaultHeaders: {
        'X-Title': 'NudgeCampaign',
        'X-Description': 'AI-first email marketing platform',
      },
    });

    // Configure fallback providers
    this.fallbackProviders = new Map([
      ['openai', new OpenAIProvider(config.openai)],
      ['anthropic', new AnthropicProvider(config.anthropic)],
    ]);
  }

  async generateContent(prompt: string, context: AIContext): Promise<AIResponse> {
    const modelConfig = this.selectOptimalModel(prompt, context);
    
    try {
      const response = await this.client.chat.completions.create({
        model: modelConfig.model,
        messages: this.buildMessages(prompt, context),
        temperature: modelConfig.temperature,
        max_tokens: modelConfig.maxTokens,
        // OpenRouter-specific optimizations
        route: modelConfig.routing,
        stream: false,
      });

      return this.parseResponse(response, modelConfig);
    } catch (error) {
      // Intelligent fallback handling
      return this.handleFailureWithFallback(prompt, context, error);
    }
  }
}

1.2 Model Selection Strategy

Intelligent Model Routing

interface ModelConfig {
  model: string;
  temperature: number;
  maxTokens: number;
  routing: 'cost' | 'performance' | 'reliability';
  costPerToken: number;
  averageLatency: number;
  successRate: number;
}

class ModelSelector {
  private modelConfigs: Map<string, ModelConfig> = new Map([
    // Cost-optimized models for simple tasks
    ['google/gemma-2-9b-it', {
      model: 'google/gemma-2-9b-it',
      temperature: 0.7,
      maxTokens: 1000,
      routing: 'cost',
      costPerToken: 0.0001,
      averageLatency: 800,
      successRate: 0.95,
    }],
    
    // Performance models for complex reasoning
    ['anthropic/claude-3.5-sonnet', {
      model: 'anthropic/claude-3.5-sonnet',
      temperature: 0.7,
      maxTokens: 2000,
      routing: 'performance',
      costPerToken: 0.003,
      averageLatency: 1200,
      successRate: 0.98,
    }],
    
    // Reliability models for critical operations
    ['openai/gpt-4', {
      model: 'openai/gpt-4',
      temperature: 0.7,
      maxTokens: 1500,
      routing: 'reliability',
      costPerToken: 0.03,
      averageLatency: 2000,
      successRate: 0.99,
    }],
  ]);

  selectOptimalModel(prompt: string, context: AIContext): ModelConfig {
    // Analyze prompt complexity and business requirements
    const complexity = this.analyzePromptComplexity(prompt);
    const businessCriticality = this.assessBusinessCriticality(context);
    const budgetConstraint = this.getBudgetConstraint(context);

    // Route based on requirements
    if (businessCriticality === 'high' || complexity === 'high') {
      return this.modelConfigs.get('anthropic/claude-3.5-sonnet')!;
    }
    
    if (budgetConstraint === 'strict' && complexity === 'low') {
      return this.modelConfigs.get('google/gemma-2-9b-it')!;
    }

    // Default to balanced performance model
    return this.modelConfigs.get('openai/gpt-4')!;
  }

  private analyzePromptComplexity(prompt: string): 'low' | 'medium' | 'high' {
    const indicators = {
      length: prompt.length,
      hasMultiStep: /step.*step|first.*then.*finally/i.test(prompt),
      hasLogicalReasoning: /because|therefore|if.*then|analyze/i.test(prompt),
      hasCreativeElements: /creative|innovative|brainstorm|design/i.test(prompt),
    };

    let score = 0;
    if (indicators.length > 500) score += 1;
    if (indicators.hasMultiStep) score += 2;
    if (indicators.hasLogicalReasoning) score += 2;
    if (indicators.hasCreativeElements) score += 1;

    if (score >= 4) return 'high';
    if (score >= 2) return 'medium';
    return 'low';
  }
}

1.3 Cost Optimization & Monitoring

Usage Tracking and Optimization

interface UsageMetrics {
  modelUsage: Map<string, number>;
  costByModel: Map<string, number>;
  latencyByModel: Map<string, number>;
  successRateByModel: Map<string, number>;
  dailySpend: number;
  monthlySpend: number;
  budgetRemaining: number;
}

class AIUsageMonitor {
  private metrics: UsageMetrics;
  private budgetLimits: {
    daily: number;
    monthly: number;
    perUser: number;
  };

  async trackUsage(modelUsed: string, tokenCount: number, cost: number, latency: number, success: boolean) {
    // Update usage metrics
    this.metrics.modelUsage.set(
      modelUsed, 
      (this.metrics.modelUsage.get(modelUsed) || 0) + tokenCount
    );
    
    this.metrics.costByModel.set(
      modelUsed,
      (this.metrics.costByModel.get(modelUsed) || 0) + cost
    );

    // Check budget constraints
    if (this.metrics.dailySpend > this.budgetLimits.daily * 0.9) {
      await this.triggerCostOptimization();
    }

    // Update model performance metrics for future routing decisions
    await this.updateModelPerformanceMetrics(modelUsed, latency, success);
  }

  private async triggerCostOptimization() {
    // Switch to more cost-effective models
    await this.notifyAdmins('Approaching daily AI budget limit');
    
    // Temporarily route all requests to cost-optimized models
    this.temporaryRoutingOverride = {
      preferCostOptimized: true,
      until: Date.now() + (24 * 60 * 60 * 1000), // 24 hours
    };
  }

  generateCostReport(): CostReport {
    return {
      totalSpend: this.metrics.monthlySpend,
      spendByModel: Object.fromEntries(this.metrics.costByModel),
      averageCostPerRequest: this.calculateAverageCostPerRequest(),
      projectedMonthlySpend: this.projectMonthlySpend(),
      recommendations: this.generateOptimizationRecommendations(),
    };
  }
}

---

Section 2: Intent Analysis & Classification

Business-Specific Intent Engine

NudgeCampaign uses a specialized intent classification system optimized for email marketing conversations.

2.1 Intent Taxonomy

Core Intent Categories

enum EmailMarketingIntent {
  // Campaign Management
  CREATE_CAMPAIGN = 'create_campaign',
  EDIT_CAMPAIGN = 'edit_campaign',
  LAUNCH_CAMPAIGN = 'launch_campaign',
  PAUSE_CAMPAIGN = 'pause_campaign',
  DUPLICATE_CAMPAIGN = 'duplicate_campaign',
  
  // Content Creation
  WRITE_EMAIL = 'write_email',
  IMPROVE_SUBJECT = 'improve_subject',
  CREATE_TEMPLATE = 'create_template',
  PERSONALIZE_CONTENT = 'personalize_content',
  A_B_TEST_CONTENT = 'ab_test_content',
  
  // Audience Management
  SEGMENT_AUDIENCE = 'segment_audience',
  IMPORT_CONTACTS = 'import_contacts',
  CLEAN_LIST = 'clean_list',
  MANAGE_UNSUBSCRIBES = 'manage_unsubscribes',
  
  // Analytics & Optimization
  ANALYZE_PERFORMANCE = 'analyze_performance',
  COMPARE_CAMPAIGNS = 'compare_campaigns',
  OPTIMIZE_DELIVERABILITY = 'optimize_deliverability',
  TROUBLESHOOT_ISSUES = 'troubleshoot_issues',
  PREDICT_PERFORMANCE = 'predict_performance',
  
  // Automation & Workflows
  CREATE_AUTOMATION = 'create_automation',
  MODIFY_WORKFLOW = 'modify_workflow',
  SET_TRIGGERS = 'set_triggers',
  SCHEDULE_EMAILS = 'schedule_emails',
  
  // Learning & Support
  LEARN_FEATURE = 'learn_feature',
  GET_HELP = 'get_help',
  REQUEST_CONSULTATION = 'request_consultation',
  REPORT_BUG = 'report_bug',
}

interface Intent {
  type: EmailMarketingIntent;
  confidence: number;
  entities: IntentEntities;
  context: IntentContext;
  requiredClarifications: string[];
  suggestedActions: ActionSuggestion[];
}

2.2 Multi-Stage Intent Processing

Hierarchical Intent Analysis

class EmailMarketingIntentAnalyzer {
  private intentClassifier: IntentClassifier;
  private entityExtractor: EntityExtractor;
  private contextAnalyzer: ContextAnalyzer;

  async analyzeIntent(userInput: string, conversationContext: ConversationContext): Promise<Intent> {
    // Stage 1: Primary intent classification
    const primaryIntent = await this.classifyPrimaryIntent(userInput, conversationContext);
    
    // Stage 2: Entity extraction
    const entities = await this.extractEntities(userInput, primaryIntent);
    
    // Stage 3: Context enrichment
    const enrichedContext = await this.enrichWithBusinessContext(
      primaryIntent, 
      entities, 
      conversationContext
    );
    
    // Stage 4: Validation and confidence scoring
    const validatedIntent = await this.validateAndScore(
      primaryIntent, 
      entities, 
      enrichedContext
    );

    return validatedIntent;
  }

  private async classifyPrimaryIntent(
    input: string, 
    context: ConversationContext
  ): Promise<EmailMarketingIntent> {
    // Use OpenRouter with specialized email marketing model
    const prompt = this.buildIntentClassificationPrompt(input, context);
    
    const response = await this.aiProvider.generateContent(prompt, {
      model: 'anthropic/claude-3.5-sonnet', // High accuracy for classification
      temperature: 0.1, // Low temperature for consistent classification
      maxTokens: 100,
    });

    return this.parseIntentFromResponse(response);
  }

  private buildIntentClassificationPrompt(input: string, context: ConversationContext): string {
    return `
You are an expert email marketing assistant. Classify the user's intent based on their input.

User Input: "${input}"

Conversation Context:
- Previous messages: ${context.previousMessages.slice(-3).join(', ')}
- Current campaign: ${context.activeCampaign || 'None'}
- User experience level: ${context.userProfile.experienceLevel}
- Business type: ${context.businessProfile.industry}

Available Intent Categories:
${Object.values(EmailMarketingIntent).join(', ')}

Respond with exactly one intent category that best matches the user's request.
Consider the context and be specific about the user's immediate need.

Intent:`;
  }
}

2.3 Context-Aware Entity Extraction

Business Context Integration

interface IntentEntities {
  // Campaign-related entities
  campaignName?: string;
  campaignType?: 'welcome' | 'promotional' | 'nurture' | 'transactional';
  targetAudience?: string;
  sendTime?: Date;
  frequency?: string;
  
  // Content-related entities
  subject?: string;
  contentTopic?: string;
  tone?: 'professional' | 'casual' | 'urgent' | 'friendly';
  callToAction?: string;
  
  // Audience-related entities
  segmentCriteria?: string[];
  listName?: string;
  contactCount?: number;
  
  // Performance-related entities
  metrics?: ('open_rate' | 'click_rate' | 'conversion_rate' | 'revenue')[];
  timeRange?: string;
  compareWith?: string;
  
  // Technical entities
  integrations?: string[];
  automationTrigger?: string;
  conditions?: string[];
}

class EntityExtractor {
  async extractEntities(input: string, intent: EmailMarketingIntent): Promise<IntentEntities> {
    // Use specialized extraction prompts based on intent type
    const extractionPrompt = this.buildExtractionPrompt(input, intent);
    
    const response = await this.aiProvider.generateContent(extractionPrompt, {
      model: 'google/gemma-2-9b-it', // Cost-effective for structured extraction
      temperature: 0.2,
      maxTokens: 300,
    });

    return this.parseEntitiesFromResponse(response, intent);
  }

  private buildExtractionPrompt(input: string, intent: EmailMarketingIntent): string {
    const relevantFields = this.getRelevantFieldsForIntent(intent);
    
    return `
Extract specific entities from this email marketing request.

User Input: "${input}"
Intent: ${intent}

Extract only the following relevant fields as JSON:
${relevantFields.map(field => `- ${field}: (if mentioned)`).join('\n')}

Return valid JSON with only the fields that are explicitly mentioned or can be inferred:
`;
  }

  private getRelevantFieldsForIntent(intent: EmailMarketingIntent): string[] {
    const fieldMap: Record<EmailMarketingIntent, string[]> = {
      [EmailMarketingIntent.CREATE_CAMPAIGN]: [
        'campaignName', 'campaignType', 'targetAudience', 'contentTopic'
      ],
      [EmailMarketingIntent.WRITE_EMAIL]: [
        'subject', 'contentTopic', 'tone', 'callToAction', 'targetAudience'
      ],
      [EmailMarketingIntent.ANALYZE_PERFORMANCE]: [
        'metrics', 'timeRange', 'campaignName', 'compareWith'
      ],
      [EmailMarketingIntent.SEGMENT_AUDIENCE]: [
        'segmentCriteria', 'listName', 'contactCount'
      ],
      // ... more mappings
    };

    return fieldMap[intent] || [];
  }
}

---

Section 3: Safety & Validation Systems

Multi-Layer Content Safety

Every AI-generated content passes through multiple validation layers before reaching users or being sent as emails.

3.1 Content Safety Pipeline

Comprehensive Validation Architecture

interface ValidationResult {
  isValid: boolean;
  confidence: number;
  issues: ValidationIssue[];
  suggestions: string[];
  blockers: string[]; // Issues that prevent proceeding
  warnings: string[]; // Issues that should be reviewed
}

interface ValidationIssue {
  type: 'spam' | 'brand' | 'legal' | 'accessibility' | 'performance' | 'safety';
  severity: 'error' | 'warning' | 'info';
  message: string;
  suggestion?: string;
  autoFixable: boolean;
}

class ContentSafetyPipeline {
  private validators: ValidationRule[] = [
    new SpamDetectionValidator(),
    new BrandComplianceValidator(),
    new LegalComplianceValidator(),
    new AccessibilityValidator(),
    new PerformanceValidator(),
    new SafetyValidator(),
  ];

  async validateContent(
    content: string, 
    contentType: 'email' | 'subject' | 'template',
    context: BusinessContext
  ): Promise<ValidationResult> {
    const results = await Promise.all(
      this.validators.map(validator => 
        validator.validate(content, contentType, context)
      )
    );

    return this.aggregateResults(results);
  }

  private aggregateResults(results: ValidationResult[]): ValidationResult {
    const allIssues = results.flatMap(r => r.issues);
    const blockers = allIssues
      .filter(issue => issue.severity === 'error')
      .map(issue => issue.message);
    const warnings = allIssues
      .filter(issue => issue.severity === 'warning')
      .map(issue => issue.message);

    return {
      isValid: blockers.length === 0,
      confidence: this.calculateOverallConfidence(results),
      issues: allIssues,
      suggestions: this.generateImprovementSuggestions(allIssues),
      blockers,
      warnings,
    };
  }
}

3.2 Spam Detection & Deliverability

Advanced Spam Score Analysis

class SpamDetectionValidator implements ValidationRule {
  private spamTriggers = {
    subject: [
      { pattern: /FREE!/gi, weight: 0.3, message: 'Avoid ALL CAPS "FREE"' },
      { pattern: /URGENT!/gi, weight: 0.25, message: 'Urgent language triggers spam filters' },
      { pattern: /\$\$\$+/g, weight: 0.4, message: 'Multiple dollar signs are spam indicators' },
      { pattern: /click here/gi, weight: 0.2, message: 'Generic CTAs reduce deliverability' },
    ],
    content: [
      { pattern: /make money fast/gi, weight: 0.5, message: 'Money-making claims are high-risk' },
      { pattern: /guaranteed/gi, weight: 0.3, message: 'Guarantee claims should be avoided' },
      { pattern: /act now/gi, weight: 0.25, message: 'High-pressure language triggers filters' },
    ],
  };

  async validate(
    content: string, 
    contentType: 'email' | 'subject' | 'template',
    context: BusinessContext
  ): Promise<ValidationResult> {
    const triggers = contentType === 'subject' 
      ? this.spamTriggers.subject 
      : this.spamTriggers.content;

    let spamScore = 0;
    const issues: ValidationIssue[] = [];

    for (const trigger of triggers) {
      const matches = content.match(trigger.pattern);
      if (matches) {
        spamScore += trigger.weight * matches.length;
        issues.push({
          type: 'spam',
          severity: spamScore > 0.7 ? 'error' : 'warning',
          message: trigger.message,
          suggestion: this.generateAlternativeSuggestion(trigger.pattern),
          autoFixable: true,
        });
      }
    }

    // Additional deliverability checks
    const deliverabilityIssues = await this.checkDeliverabilityFactors(content, contentType);
    issues.push(...deliverabilityIssues);

    return {
      isValid: spamScore < 0.7,
      confidence: Math.max(0, 1 - spamScore),
      issues,
      suggestions: this.generateSpamOptimizations(content, spamScore),
      blockers: issues.filter(i => i.severity === 'error').map(i => i.message),
      warnings: issues.filter(i => i.severity === 'warning').map(i => i.message),
    };
  }

  private async checkDeliverabilityFactors(
    content: string, 
    contentType: string
  ): Promise<ValidationIssue[]> {
    const issues: ValidationIssue[] = [];

    // Subject line length check
    if (contentType === 'subject' && content.length > 50) {
      issues.push({
        type: 'performance',
        severity: 'warning',
        message: 'Subject line may be truncated on mobile devices',
        suggestion: 'Keep subject lines under 50 characters for optimal display',
        autoFixable: false,
      });
    }

    // HTML/text ratio for email content
    if (contentType === 'email') {
      const htmlContent = content.match(/<[^>]*>/g)?.join('') || '';
      const textContent = content.replace(/<[^>]*>/g, '');
      const htmlRatio = htmlContent.length / content.length;

      if (htmlRatio > 0.3) {
        issues.push({
          type: 'spam',
          severity: 'warning',
          message: 'High HTML-to-text ratio may impact deliverability',
          suggestion: 'Include more text content relative to HTML markup',
          autoFixable: false,
        });
      }
    }

    return issues;
  }
}

3.3 Brand Compliance Validation

Automated Brand Voice Checking

class BrandComplianceValidator implements ValidationRule {
  async validate(
    content: string,
    contentType: string,
    context: BusinessContext
  ): Promise<ValidationResult> {
    const brandProfile = await this.getBrandProfile(context.businessId);
    
    // Use AI to analyze brand voice consistency
    const brandAnalysisPrompt = `
Analyze this ${contentType} content for brand voice consistency:

Content: "${content}"

Brand Profile:
- Tone: ${brandProfile.tone}
- Voice: ${brandProfile.voice}
- Key values: ${brandProfile.values.join(', ')}
- Industry: ${brandProfile.industry}
- Prohibited words/phrases: ${brandProfile.prohibitedTerms.join(', ')}

Rate consistency (0-1) and identify specific issues:
1. Tone alignment
2. Voice consistency  
3. Value alignment
4. Prohibited term usage
5. Industry appropriateness

Return JSON format:
{
  "consistencyScore": 0.8,
  "issues": [
    {
      "aspect": "tone",
      "severity": "warning",
      "message": "Content tone is more casual than brand profile",
      "suggestion": "Use more professional language"
    }
  ]
}
`;

    const response = await this.aiProvider.generateContent(brandAnalysisPrompt, {
      model: 'anthropic/claude-3.5-sonnet', // High accuracy for nuanced analysis
      temperature: 0.1,
      maxTokens: 500,
    });

    return this.parseBrandAnalysisResponse(response);
  }

  private async getBrandProfile(businessId: string): Promise<BrandProfile> {
    // Retrieve stored brand profile
    return this.brandProfileStore.get(businessId);
  }
}

---

This is Section 1-3 of the AI Standards. Continue with Section 4 (Prompt Engineering) and Section 5 (Quality Assurance)?