@realtimex/email-automator 2.6.2 → 2.6.5

package/api/src/middleware/validation.ts

@@ -87,8 +87,12 @@ export const schemas = {
     }),
 
     // Rule schemas - supports both single action (legacy) and actions array
+    // Now includes description and intent for context-aware AI matching
     createRule: z.object({
         name: z.string().min(1).max(100),
+        description: z.string().max(500).optional(),
+        intent: z.string().max(200).optional(),
+        priority: z.number().int().min(0).max(100).optional(),
         condition: z.record(z.unknown()),
         action: z.enum(['delete', 'archive', 'draft', 'star', 'read']).optional(),
         actions: z.array(z.enum(['delete', 'archive', 'draft', 'star', 'read'])).optional(),
@@ -100,6 +104,9 @@ export const schemas = {
 
     updateRule: z.object({
         name: z.string().min(1).max(100).optional(),
+        description: z.string().max(500).optional(),
+        intent: z.string().max(200).optional(),
+        priority: z.number().int().min(0).max(100).optional(),
         condition: z.record(z.unknown()).optional(),
         action: z.enum(['delete', 'archive', 'draft', 'star', 'read']).optional(),
         actions: z.array(z.enum(['delete', 'archive', 'draft', 'star', 'read'])).optional(),

package/api/src/routes/rules.ts

@@ -68,7 +68,12 @@ router.patch('/:ruleId',
     validateBody(schemas.updateRule),
     asyncHandler(async (req, res) => {
         const { ruleId } = req.params;
-        const updates = req.body;
+        const updates = { ...req.body };
+
+        // Ensure legacy action is in sync if actions array is provided
+        if (updates.actions && Array.isArray(updates.actions) && updates.actions.length > 0) {
+            updates.action = updates.actions[0];
+        }
 
         const { data, error } = await req.supabase!
             .from('rules')
@@ -81,7 +86,7 @@ router.patch('/:ruleId',
         if (error) throw error;
         if (!data) throw new NotFoundError('Rule');
 
-        logger.info('Rule updated', { ruleId, userId: req.user!.id });
+        logger.info('Rule updated', { ruleId, actions: data.actions, userId: req.user!.id });
 
         res.json({ rule: data });
     })

package/api/src/services/intelligence.ts

@@ -30,6 +30,44 @@ export const EmailAnalysisSchema = z.object({
 
 export type EmailAnalysis = z.infer<typeof EmailAnalysisSchema>;
 
+// Context-Aware Analysis Schema - AI evaluates email against user's rules
+export const ContextAwareAnalysisSchema = z.object({
+    // Classification (kept for UI/logging)
+    summary: z.string().describe('A brief summary of the email content'),
+    category: z.enum(['spam', 'newsletter', 'promotional', 'transactional', 'social', 'support', 'client', 'internal', 'personal', 'other'])
+        .describe('The category of the email'),
+    priority: z.enum(['High', 'Medium', 'Low'])
+        .describe('The urgency of the email'),
+
+    // Rule Matching (core of context-aware engine)
+    matched_rule: z.object({
+        rule_id: z.string().nullable().describe('ID of the matched rule, or null if no match'),
+        rule_name: z.string().nullable().describe('Name of the matched rule'),
+        confidence: z.number().min(0).max(1).describe('Confidence score for the match (0-1)'),
+        reasoning: z.string().describe('Explanation of why this rule was matched or why no rule matched'),
+    }),
+
+    // Actions to execute (derived from matched rule)
+    actions_to_execute: z.array(z.enum(['none', 'delete', 'archive', 'draft', 'read', 'star']))
+        .describe('Actions to execute based on the matched rule'),
+
+    // Intent-aware draft content (if draft action is included)
+    draft_content: z.string().optional()
+        .describe('Generated draft reply if the action includes drafting'),
+});
+
+export type ContextAwareAnalysis = z.infer<typeof ContextAwareAnalysisSchema>;
+
+// Rule context for AI matching
+export interface RuleContext {
+    id: string;
+    name: string;
+    description?: string;
+    intent?: string;
+    actions: string[];
+    draft_instructions?: string;
+}
+
 export interface EmailContext {
     subject: string;
     sender: string;
@@ -87,7 +125,7 @@ export class IntelligenceService {
 
     async analyzeEmail(content: string, context: EmailContext, eventLogger?: EventLogger, emailId?: string): Promise<EmailAnalysis | null> {
         console.log('[Intelligence] analyzeEmail called for:', context.subject);
-        
+
         if (!this.isReady()) {
             console.log('[Intelligence] Not ready, skipping');
             logger.warn('Intelligence service not ready, skipping analysis');
@@ -99,7 +137,7 @@ export class IntelligenceService {
 
         // 1. Prepare Content and Signals
         const cleanedContent = ContentCleaner.cleanEmailBody(content).substring(0, 2500);
-        
+
         const metadataSignals = [];
         if (context.metadata?.listUnsubscribe) metadataSignals.push('- Contains Unsubscribe header (High signal for Newsletter/Promo)');
         if (context.metadata?.autoSubmitted && context.metadata.autoSubmitted !== 'no') metadataSignals.push(`- Auto-Submitted: ${context.metadata.autoSubmitted}`);
@@ -148,7 +186,7 @@ REQUIRED JSON STRUCTURE:
         if (eventLogger) {
             console.log('[Intelligence] Logging "Thinking" event');
             try {
-                await eventLogger.info('Thinking', `Analyzing email: ${context.subject}`, { 
+                await eventLogger.info('Thinking', `Analyzing email: ${context.subject}`, {
                     model: this.model,
                     system_prompt: systemPrompt,
                     content_preview: cleanedContent,
@@ -174,12 +212,12 @@ REQUIRED JSON STRUCTURE:
 
             rawResponse = response.choices[0]?.message?.content || '';
             console.log('[Intelligence] Raw LLM Response received (length:', rawResponse.length, ')');
-            
+
             // Clean the response: Find first '{' and last '}'
             let jsonStr = rawResponse.trim();
             const startIdx = jsonStr.indexOf('{');
             const endIdx = jsonStr.lastIndexOf('}');
-            
+
             if (startIdx === -1 || endIdx === -1) {
                 throw new Error('Response did not contain a valid JSON object (missing curly braces)');
             }
@@ -197,7 +235,7 @@ REQUIRED JSON STRUCTURE:
             if (eventLogger && emailId) {
                 await eventLogger.analysis('Decided', emailId, {
                     ...validated,
-                    _raw_response: rawResponse 
+                    _raw_response: rawResponse
                 });
             }
 
@@ -251,6 +289,189 @@ Please write a reply.`,
         }
     }
 
+    /**
+     * Context-Aware Analysis: AI evaluates email against user's rules semantically
+     * This is the core of the new automation engine
+     * 
+     * @param compiledRulesContext - Pre-compiled rules context string (from user_settings.compiled_rule_context)
+     *                               OR RuleContext[] for backwards compatibility
+     */
+    async analyzeEmailWithRules(
+        content: string,
+        context: EmailContext,
+        compiledRulesContext: string | RuleContext[],
+        eventLogger?: EventLogger,
+        emailId?: string
+    ): Promise<ContextAwareAnalysis | null> {
+        console.log('[Intelligence] analyzeEmailWithRules called for:', context.subject);
+
+        if (!this.isReady()) {
+            console.log('[Intelligence] Not ready, skipping');
+            logger.warn('Intelligence service not ready, skipping analysis');
+            if (eventLogger) {
+                await eventLogger.info('Skipped', 'AI Analysis skipped: Model not configured.', undefined, emailId);
+            }
+            return null;
+        }
+
+        // Prepare content
+        const cleanedContent = ContentCleaner.cleanEmailBody(content).substring(0, 2500);
+
+        // Use pre-compiled context if string, otherwise build from RuleContext[] (backwards compat)
+        let rulesContext: string;
+        let rulesCount: number;
+
+        if (typeof compiledRulesContext === 'string') {
+            // Fast path: use pre-compiled context
+            rulesContext = compiledRulesContext || '\n[No rules defined - analyze email but take no actions]\n';
+            rulesCount = (rulesContext.match(/Rule \d+/g) || []).length;
+        } else {
+            // Backwards compatibility: build from RuleContext[]
+            const rules = compiledRulesContext;
+            rulesCount = rules.length;
+            rulesContext = rules.length > 0
+                ? rules.map((r, i) => `
+### Rule ${i + 1}: "${r.name}" (ID: ${r.id})
+- Description: ${r.description || 'No description provided'}
+- Intent: ${r.intent || 'General automation'}
+- Actions: ${r.actions.join(', ')}
+${r.draft_instructions ? `- Draft Instructions: "${r.draft_instructions}"` : ''}
+`).join('\n')
+                : '\n[No rules defined - analyze email but take no actions]\n';
+        }
+
+        const systemPrompt = `You are an AI Email Automation Agent.
+
+## Your Operating Rules
+The user has defined the following automation rules. Your job is to:
+1. Analyze the incoming email
+2. Determine if ANY rule semantically matches this email's context
+3. Match based on INTENT, not just keywords
+
+${rulesContext}
+
+## Category Definitions (choose the most accurate)
+- **client**: Business inquiries, RFPs, quote requests, project discussions, potential customers reaching out
+- **support**: Help requests, bug reports, technical questions from existing users
+- **internal**: Messages from colleagues, team communications
+- **transactional**: Receipts, confirmations, shipping updates, account notifications
+- **newsletter**: Subscribed content, digests, updates from services you signed up for
+- **promotional**: UNSOLICITED marketing, cold sales pitches, ads - NOT legitimate business inquiries
+- **spam**: Scams, phishing, junk mail
+- **social**: Social media notifications, friend requests
+- **personal**: Friends, family, personal matters
+- **other**: Anything that doesn't fit above
+
+## Matching Guidelines
+- A "decline sales" rule should match ANY sales pitch, not just ones with "sales" in the subject
+- Match the rule that best fits the USER'S INTENT
+- Only match if you are confident (>= 0.7 confidence)
+- If no rule clearly matches, return null for rule_id
+- If a matched rule includes "draft" action, generate an appropriate draft using the rule's intent
+
+## CRITICAL: Distinguish Between Inbound vs Outbound
+**INBOUND (Client Inquiries - NOT promotional):**
+- User is RECEIVING a request for quote/proposal/service
+- Examples: "Please send me a quote", "RFP: [project]", "Can you provide pricing", "I need a quote asap"
+- Category: client, support, or transactional (NEVER promotional)
+
+**OUTBOUND (Sales/Marketing - IS promotional):**
+- User is RECEIVING a sales pitch or marketing message
+- Examples: "Get a FREE quote today!", "Limited offer", "Don't miss out", "Special discount"
+- Category: promotional, spam, or newsletter
+
+**Key Distinction:** If someone is ASKING the user for something (quote, proposal, service), it's a CLIENT INQUIRY, not promotional content.
+
+## Email Context
+- Current Date: ${new Date().toISOString()}
+- Subject: ${context.subject}
+- From: ${context.sender}
+- Date: ${context.date}
+
+## Required JSON Response
+{
+  "summary": "Brief summary of the email",
+  "category": "spam|newsletter|promotional|transactional|social|support|client|internal|personal|other",
+  "priority": "High|Medium|Low",
+  "matched_rule": {
+    "rule_id": "UUID or null",
+    "rule_name": "Rule name or null",
+    "confidence": 0.0-1.0,
+    "reasoning": "Why this rule was or wasn't matched"
+  },
+  "actions_to_execute": ["none"] or ["archive", "read", etc.],
+  "draft_content": "Optional: draft reply if action includes 'draft'"
+}
+
+Return ONLY valid JSON.`;
+
+        // Log thinking phase
+        if (eventLogger) {
+            try {
+                await eventLogger.info('Thinking', `Context-aware analysis: ${context.subject}`, {
+                    model: this.model,
+                    system_prompt: systemPrompt,
+                    content_preview: cleanedContent,
+                    rules_count: rulesCount,
+                }, emailId);
+            } catch (err) {
+                console.error('[Intelligence] Failed to log thinking event:', err);
+            }
+        }
+
+        let rawResponse = '';
+        try {
+            const response = await this.client!.chat.completions.create({
+                model: this.model,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: cleanedContent || '[Empty email body]' },
+                ],
+                temperature: 0.1,
+            });
+
+            rawResponse = response.choices[0]?.message?.content || '';
+            console.log('[Intelligence] Context-aware response received (length:', rawResponse.length, ')');
+
+            // Parse JSON from response
+            let jsonStr = rawResponse.trim();
+            const startIdx = jsonStr.indexOf('{');
+            const endIdx = jsonStr.lastIndexOf('}');
+
+            if (startIdx === -1 || endIdx === -1) {
+                throw new Error('Response did not contain a valid JSON object');
+            }
+
+            jsonStr = jsonStr.substring(startIdx, endIdx + 1);
+            const parsed = JSON.parse(jsonStr);
+            const validated = ContextAwareAnalysisSchema.parse(parsed);
+
+            logger.debug('Context-aware analysis complete', {
+                matched_rule: validated.matched_rule.rule_name,
+                confidence: validated.matched_rule.confidence,
+                actions: validated.actions_to_execute,
+            });
+
+            if (eventLogger && emailId) {
+                await eventLogger.analysis('Decided', emailId, {
+                    ...validated,
+                    _raw_response: rawResponse
+                });
+            }
+
+            return validated;
+        } catch (error) {
+            console.error('[Intelligence] Context-aware analysis failed:', error);
+            if (eventLogger) {
+                await eventLogger.error('Error', {
+                    error: error instanceof Error ? error.message : String(error),
+                    raw_response: rawResponse || 'No response received from LLM'
+                }, emailId);
+            }
+            return null;
+        }
+    }
+
     async testConnection(): Promise<{ success: boolean; message: string }> {
         if (!this.isReady()) {
             return { success: false, message: 'Intelligence service not initialized. Check your API Key.' };

package/api/src/services/processor.ts

@@ -4,7 +4,7 @@ import { createLogger } from '../utils/logger.js';
 import { config } from '../config/index.js';
 import { getGmailService, GmailMessage } from './gmail.js';
 import { getMicrosoftService, OutlookMessage } from './microsoft.js';
-import { getIntelligenceService, EmailAnalysis } from './intelligence.js';
+import { getIntelligenceService, EmailAnalysis, ContextAwareAnalysis, RuleContext } from './intelligence.js';
 import { getStorageService } from './storage.js';
 import { EmailAccount, Email, Rule, ProcessingLog } from './supabase.js';
 import { EventLogger } from './eventLogger.js';
@@ -551,7 +551,39 @@ export class EmailProcessorService {
                 mailer: parsed.headers.get('x-mailer')?.toString()
             };
 
-            // 3. Analyze with AI
+            // 3. Fetch account for action execution
+            const { data: account } = await this.supabase
+                .from('email_accounts')
+                .select('*')
+                .eq('id', email.account_id)
+                .single();
+
+            // 4. Fetch pre-compiled rule context (fast path - no loop/formatting)
+            // Falls back to building context if not cached
+            let compiledContext: string | null = settings?.compiled_rule_context || null;
+            
+            // Fetch rules for action execution (need attachments, instructions)
+            const { data: rules } = await this.supabase
+                .from('rules')
+                .select('*')
+                .eq('user_id', userId)
+                .eq('is_enabled', true)
+                .order('priority', { ascending: false });
+
+            // Fallback: build context if not pre-compiled
+            if (!compiledContext && rules && rules.length > 0) {
+                compiledContext = rules.map((r, i) => 
+                    `Rule ${i + 1} [ID: ${r.id}]\n` +
+                    `  Name: ${r.name}\n` +
+                    (r.description ? `  Description: ${r.description}\n` : '') +
+                    (r.intent ? `  Intent: ${r.intent}\n` : '') +
+                    `  Actions: ${r.actions?.join(', ') || r.action || 'none'}\n` +
+                    (r.instructions ? `  Draft Instructions: ${r.instructions}\n` : '') +
+                    '\n'
+                ).join('');
+            }
+
+            // 5. Context-Aware Analysis: AI evaluates email against user's rules
             const intelligenceService = getIntelligenceService(
                 settings?.llm_model || settings?.llm_base_url || settings?.llm_api_key
                     ? {
@@ -562,53 +594,76 @@ export class EmailProcessorService {
                     : undefined
             );
 
-            const analysis = await intelligenceService.analyzeEmail(cleanContent, {
-                subject: email.subject || '',
-                sender: email.sender || '',
-                date: email.date || '',
-                metadata,
-                userPreferences: {
-                    autoTrashSpam: settings?.auto_trash_spam,
-                    smartDrafts: settings?.smart_drafts,
+            const analysis = await intelligenceService.analyzeEmailWithRules(
+                cleanContent,
+                {
+                    subject: email.subject || '',
+                    sender: email.sender || '',
+                    date: email.date || '',
+                    metadata,
+                    userPreferences: {
+                        autoTrashSpam: settings?.auto_trash_spam,
+                        smartDrafts: settings?.smart_drafts,
+                    },
                 },
-            }, eventLogger || undefined, email.id);
+                compiledContext || '',  // Pre-compiled context (fast path)
+                eventLogger || undefined,
+                email.id
+            );
 
             if (!analysis) {
                 throw new Error('AI analysis returned no result');
             }
 
-            // 4. Update the email record with results
+            // 6. Update the email record with context-aware results
             await this.supabase
                 .from('emails')
                 .update({
                     category: analysis.category,
-                    is_useless: analysis.is_useless,
                     ai_analysis: analysis as any,
-                    suggested_actions: analysis.suggested_actions || [],
-                    suggested_action: analysis.suggested_actions?.[0] || 'none',
+                    suggested_actions: analysis.actions_to_execute || [],
+                    suggested_action: analysis.actions_to_execute?.[0] || 'none',
+                    matched_rule_id: analysis.matched_rule.rule_id,
+                    matched_rule_confidence: analysis.matched_rule.confidence,
                     processing_status: 'completed'
                 })
                 .eq('id', email.id);
 
-            // 5. Execute automation rules
-            // Fetch account and rules needed for execution
-            const { data: account } = await this.supabase
-                .from('email_accounts')
-                .select('*')
-                .eq('id', email.account_id)
-                .single();
-
-            const { data: rules } = await this.supabase
-                .from('rules')
-                .select('*')
-                .eq('user_id', userId)
-                .eq('is_enabled', true);
+            // 7. Execute actions if rule matched with sufficient confidence
+            if (account && analysis.matched_rule.rule_id && analysis.matched_rule.confidence >= 0.7) {
+                const matchedRule = rules?.find(r => r.id === analysis.matched_rule.rule_id);
+                
+                if (eventLogger) {
+                    await eventLogger.info('Rule Matched', 
+                        `"${analysis.matched_rule.rule_name}" matched with ${(analysis.matched_rule.confidence * 100).toFixed(0)}% confidence`,
+                        { reasoning: analysis.matched_rule.reasoning },
+                        email.id
+                    );
+                }
 
-            if (account && rules) {
-                const tempResult = { processed: 0, deleted: 0, drafted: 0, errors: 0 };
-                // Ensure email object for rules has the analysis fields merged in
-                const emailForRules = { ...email, ...analysis };
-                await this.executeRules(account, emailForRules as any, analysis, rules, settings, tempResult, eventLogger);
+                // Execute each action from the AI's decision
+                for (const action of analysis.actions_to_execute) {
+                    if (action === 'none') continue;
+                    
+                    // Use AI-generated draft content if available
+                    const draftContent = action === 'draft' ? analysis.draft_content : undefined;
+                    
+                    await this.executeAction(
+                        account, 
+                        email, 
+                        action as any, 
+                        draftContent, 
+                        eventLogger, 
+                        `Rule: ${matchedRule?.name || analysis.matched_rule.rule_name}`,
+                        matchedRule?.attachments
+                    );
+                }
+            } else if (eventLogger && rules && rules.length > 0) {
+                await eventLogger.info('No Match', 
+                    analysis.matched_rule.reasoning,
+                    { confidence: analysis.matched_rule.confidence },
+                    email.id
+                );
             }
 
             // Mark log as success

package/api/src/services/supabase.ts

@@ -115,10 +115,13 @@ export interface Rule {
     id: string;
     user_id: string;
     name: string;
-    condition: Record<string, unknown>;
+    description?: string;  // Semantic context for AI matching
+    intent?: string;       // The intent behind the rule (e.g., "Politely decline sales pitches")
+    priority?: number;     // Higher = evaluated first by AI
+    condition: Record<string, unknown>; // Legacy - kept for backwards compatibility
     action?: 'delete' | 'archive' | 'draft' | 'star' | 'read'; // Legacy single action
     actions?: ('delete' | 'archive' | 'draft' | 'star' | 'read')[]; // New multi-action array
-    instructions?: string;
+    instructions?: string; // Draft generation instructions
     attachments?: any[];
     is_enabled: boolean;
     created_at: string;