@realtimex/email-automator 2.6.4 → 2.7.0

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/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,
@@ -173,13 +211,14 @@ REQUIRED JSON STRUCTURE:
             });
 
             rawResponse = response.choices[0]?.message?.content || '';
-            console.log('[Intelligence] Raw LLM Response received (length:', rawResponse.length, ')');
-            
+            const usage = response.usage;
+            console.log('[Intelligence] Raw LLM Response received (length:', rawResponse.length, ')', { usage });
+
             // 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 +236,8 @@ REQUIRED JSON STRUCTURE:
             if (eventLogger && emailId) {
                 await eventLogger.analysis('Decided', emailId, {
                     ...validated,
-                    _raw_response: rawResponse 
+                    _raw_response: rawResponse,
+                    usage: usage // Include token usage
                 });
             }
 
@@ -251,6 +291,191 @@ 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 || '';
+            const usage = response.usage;
+            console.log('[Intelligence] Context-aware response received (length:', rawResponse.length, ')', { usage });
+
+            // 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,
+                    usage: usage // Include token usage
+                });
+            }
+
+            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.' };