@realtimex/email-automator 2.21.2 → 2.21.5

package/.env.example

@@ -8,10 +8,10 @@ VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
 VITE_API_URL=http://localhost:3004
 PORT=3004
 
-# OpenAI / LLM Configuration
-LLM_API_KEY=your_llm_api_key
-LLM_BASE_URL=https://api.openai.com/v1
-LLM_MODEL=gpt-4o-mini
+# LLM Configuration
+# Managed by RealTimeX SDK - No environment variables needed!
+# Configure providers via RealTimeX Desktop (port 3001) or Configuration UI
+# The SDK automatically connects to RealTimeX Desktop for AI operations
 
 # Security (required in production)
 JWT_SECRET="your-secure-jwt-secret-min-32-chars"

package/README.md

@@ -178,10 +178,11 @@ VITE_SUPABASE_ANON_KEY=your-anon-key
 VITE_API_URL=http://localhost:3004
 PORT=3004
 
-# LLM
-LLM_API_KEY=your-llm-key
-LLM_BASE_URL=https://api.openai.com/v1
-LLM_MODEL=gpt-4o-mini
+# LLM Configuration
+# Managed by RealTimeX SDK - No API keys needed!
+# 1. Start RealTimeX Desktop (port 3001)
+# 2. Configure providers via Configuration UI or RealTimeX Desktop
+# The SDK automatically handles provider discovery and routing
 
 # Development
 DISABLE_AUTH=true

package/api/src/config/index.ts

@@ -72,27 +72,29 @@ export const config = {
     scriptsDir: join(packageRoot, 'scripts'),
 
     // Supabase
+    // Supabase Configuration
+    // Primary: BYOK via Setup Wizard (credentials passed via HTTP headers)
+    // Fallback: Environment variables (for backend development/testing only)
+    // WARNING: Env var fallback will be removed in future versions - use Setup Wizard!
     supabase: {
         url: process.env.SUPABASE_URL || process.env.VITE_SUPABASE_URL || '',
         anonKey: process.env.SUPABASE_ANON_KEY || process.env.VITE_SUPABASE_ANON_KEY || '',
         serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY || '',
     },
 
-    // LLM
-    llm: {
-        apiKey: process.env.LLM_API_KEY || '',
-        baseUrl: process.env.LLM_BASE_URL,
-        model: process.env.LLM_MODEL || 'gpt-4o-mini',
-    },
+    // LLM Configuration: Managed by RealTimeX SDK (no env vars needed)
+    // Users configure providers via RealTimeX Desktop or Configuration UI
 
-    // OAuth - Gmail
+    // OAuth Configuration
+    // Primary: BYOK via Setup Wizard (stored in user_settings)
+    // Fallback: Environment variables (for backend development/testing only)
+    // WARNING: Env var fallback will be removed in future versions - use Setup Wizard!
     gmail: {
         clientId: process.env.GMAIL_CLIENT_ID || '',
         clientSecret: process.env.GMAIL_CLIENT_SECRET || '',
         redirectUri: process.env.GMAIL_REDIRECT_URI || 'urn:ietf:wg:oauth:2.0:oob',
     },
 
-    // OAuth - Microsoft
     microsoft: {
         clientId: process.env.MS_GRAPH_CLIENT_ID || '',
         tenantId: process.env.MS_GRAPH_TENANT_ID || 'common',

package/api/src/lib/agent-knowledge-base.ts

@@ -0,0 +1,83 @@
+/**
+ * Agent Knowledge Base (Backend)
+ * Provides comprehensive context about Email-Automator to the LLM
+ *
+ * This file reads from docs/AGENT-KNOWLEDGE.md which is auto-generated
+ * at build time by scripts/generate-agent-docs.ts from user documentation
+ *
+ * Sources:
+ * - docs/user-guide/*.md (primary source)
+ * - docs/README.md
+ * - CLAUDE.md (technical architecture)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Read generated documentation at runtime
+let CORE_APP_KNOWLEDGE = '';
+
+try {
+    // Try to read from generated knowledge base
+    const docsPath = path.join(__dirname, '../../../docs/AGENT-KNOWLEDGE.md');
+    CORE_APP_KNOWLEDGE = fs.readFileSync(docsPath, 'utf-8');
+    console.log('[AgentKnowledge] ✓ Loaded knowledge base from docs/AGENT-KNOWLEDGE.md');
+    console.log(`[AgentKnowledge]   Size: ${(CORE_APP_KNOWLEDGE.length / 1024).toFixed(2)} KB`);
+} catch (error) {
+    console.warn('[AgentKnowledge] ⚠️  Could not load docs/AGENT-KNOWLEDGE.md, using fallback');
+    console.warn('[AgentKnowledge]   Run: npm run build:docs');
+
+    // Fallback minimal knowledge
+    CORE_APP_KNOWLEDGE = `# Email-Automator Assistant
+
+I'm your Email-Automator assistant. I can help you with:
+- Connecting email accounts (Gmail, Outlook)
+- Creating automation rules
+- Managing drafts
+- Configuring AI and voice settings
+
+**⚠️ Note:** Full knowledge base not available. Please regenerate by running:
+\`\`\`bash
+npm run build:docs
+\`\`\`
+`;
+}
+
+export { CORE_APP_KNOWLEDGE };
+
+export function getEnhancedSystemInstruction(
+    pageId: string,
+    userInstruction: string,
+    data?: any
+): string {
+    // Base instruction with knowledge
+    let instruction = `${userInstruction}
+
+${CORE_APP_KNOWLEDGE}
+
+# Current Context
+- **Current Page**: ${pageId}
+- **Page Data**: ${JSON.stringify(data || {}, null, 2)}
+
+# Response Instructions
+
+**CRITICAL - Anti-Hallucination Rules:**
+1. ONLY answer using information explicitly documented in the knowledge base above
+2. If you don't find information about something, say: "I don't have documentation about that"
+3. NEVER invent features, buttons, settings, or workflows not documented above
+4. When uncertain, acknowledge it clearly rather than guessing
+
+**When Answering:**
+- Search the knowledge base for relevant information first
+- Reference exact page names and UI elements as documented
+- Provide step-by-step instructions when they exist in the guides
+- If user asks about a different page, guide them: "Go to [Page Name] → [Section]"
+- Use tools when available on current page
+- Be concise and accurate - better to say "I'm not sure" than provide wrong information`;
+
+    return instruction;
+}

package/api/src/middleware/validation.ts

@@ -83,6 +83,7 @@ export const schemas = {
     migrate: z.object({
         projectRef: z.string().min(1, 'Project reference is required'),
         accessToken: z.string().min(1, 'Access token is required for automatic migration'),
+        anonKey: z.string().optional(), // For knowledge base ingestion during migration
     }),
 
     // Rule schemas - supports both single action (legacy) and actions array

package/api/src/routes/agent.ts

@@ -0,0 +1,179 @@
+import { Request, Response, Router } from 'express';
+import { createClient, SupabaseClient } from '@supabase/supabase-js';
+import { AgentService } from '../services/AgentService.js';
+
+const router = Router();
+
+/**
+ * Get Supabase client from request headers (BYOK mode) or environment (server mode)
+ */
+function getSupabaseFromRequest(req: Request): SupabaseClient | null {
+    // Try request headers first (BYOK mode - credentials from Setup Wizard)
+    const headerUrl = req.headers['x-supabase-url'] as string;
+    const headerKey = req.headers['x-supabase-anon-key'] as string;
+
+    if (headerUrl && headerKey) {
+        try {
+            return createClient(headerUrl, headerKey);
+        } catch (error) {
+            console.error('[Agent API] Failed to create Supabase client from headers:', error);
+        }
+    }
+
+    // Fallback to environment variables (server mode)
+    const envUrl = process.env.SUPABASE_URL;
+    const envKey = process.env.SUPABASE_ANON_KEY;
+
+    if (envUrl && envKey) {
+        try {
+            return createClient(envUrl, envKey);
+        } catch (error) {
+            console.error('[Agent API] Failed to create Supabase client from env:', error);
+        }
+    }
+
+    return null;
+}
+
+/**
+ * POST /api/agent/chat
+ * Context-aware chat endpoint with optional RAG
+ */
+router.post('/chat', async (req: Request, res: Response) => {
+    try {
+        const userId = req.headers['x-user-id'] as string;
+        const { message, context, history } = req.body;
+
+        if (!message) {
+            return res.status(400).json({ success: false, error: 'Message is required' });
+        }
+
+        // Get Supabase client from request (BYOK) or environment
+        const supabase = getSupabaseFromRequest(req);
+
+        // If Supabase is available, use RAG-enhanced agent
+        if (supabase) {
+            console.log('[Agent API] Using RAG-enhanced agent');
+            const agentService = new AgentService(supabase);
+
+            const response = await agentService.chat(
+                userId || 'anonymous',
+                message,
+                context || { page_id: 'global' },
+                history || []
+            );
+
+            res.json({
+                success: true,
+                response
+            });
+        } else {
+            // Fallback: Basic agent without RAG
+            console.warn('[Agent API] Running without RAG - Supabase not configured');
+
+            const { SDKService } = await import('../services/SDKService.js');
+            const sdk = SDKService.getSDK();
+
+            if (!sdk) {
+                return res.status(503).json({
+                    success: false,
+                    error: 'AI service unavailable. Please ensure RealTimeX Desktop is running.'
+                });
+            }
+
+            // Build system prompt without RAG
+            const baseInstruction = context?.system_instruction ||
+                "You are a helpful Email Automator Assistant.";
+
+            let systemPrompt = `${baseInstruction}
+
+# Current Context
+- **Current Page**: ${context?.page_id || 'global'}
+- **Page Data**: ${JSON.stringify(context?.data || {}, null, 2)}
+
+# Response Instructions
+**When Answering:**
+- Provide helpful guidance based on the context
+- Use tools when available on current page
+- Be concise and actionable`;
+
+            // Add Tool Instructions if tools are available
+            if (context?.tools && context.tools.length > 0) {
+                const toolDescs = context.tools.map((t: any) => {
+                    const params = t.parameters?.properties
+                        ? Object.entries(t.parameters.properties).map(([key, val]: [string, any]) =>
+                            `${key}: ${val.type}${val.description ? ` (${val.description})` : ''}`
+                        ).join(', ')
+                        : 'none';
+                    const required = t.parameters?.required ? ` [Required: ${t.parameters.required.join(', ')}]` : '';
+                    return `- ${t.name}: ${t.description}\n  Parameters: {${params}}${required}`;
+                }).join('\n');
+
+                systemPrompt += `\n\n# AVAILABLE TOOLS\n${toolDescs}\n\n## Tool Usage Rules:
+1. To execute a tool, output the marker <<<ACTION>>> followed by a JSON object on the same line
+2. The JSON MUST have "name" (tool name) and "args" (object with parameters)
+3. Example: <<<ACTION>>>{"name": "send_draft", "args": {"draft_id": "123"}}
+4. Do NOT wrap the JSON in markdown code blocks
+5. Always include all required parameters as specified above
+6. Provide a friendly explanation BEFORE the <<<ACTION>>> marker`;
+            }
+
+            // Prepare messages
+            const historyMessages = (history || []).slice(-5).map((m: any) => ({
+                role: m.role as 'system' | 'user' | 'assistant',
+                content: m.content
+            }));
+
+            const messages = [
+                { role: 'system' as const, content: systemPrompt },
+                ...historyMessages,
+                { role: 'user' as const, content: message }
+            ];
+
+            // Call SDK
+            const { provider, model } = await SDKService.resolveChatProvider({});
+            const llmResponse = await sdk.llm.chat(messages, { provider, model });
+
+            let content = llmResponse.response?.content || "I couldn't generate a response.";
+            let action: { name: string; args: any } | undefined = undefined;
+
+            // Parse Action
+            if (content.includes('<<<ACTION>>>')) {
+                const parts = content.split('<<<ACTION>>>');
+                content = parts[0].trim();
+                try {
+                    let actionJson = parts[1].trim().replace(/```json\s*/g, '').replace(/```\s*/g, '');
+                    const parsed = JSON.parse(actionJson);
+
+                    if (parsed?.name && typeof parsed.name === 'string') {
+                        const toolExists = context?.tools?.some((t: any) => t.name === parsed.name);
+                        if (toolExists) {
+                            action = { name: parsed.name, args: parsed.args || {} };
+                        } else {
+                            content += `\n\n⚠️ Note: Tool "${parsed.name}" not available.`;
+                        }
+                    }
+                } catch (e) {
+                    content += `\n\n⚠️ Note: I tried to take an action but the format was incorrect.`;
+                }
+            }
+
+            res.json({
+                success: true,
+                response: {
+                    content,
+                    action,
+                    usage: (llmResponse.response as any)?.metrics || undefined
+                }
+            });
+        }
+    } catch (error: any) {
+        console.error('[Agent API] Chat failed:', error);
+        res.status(500).json({
+            success: false,
+            error: error.message
+        });
+    }
+});
+
+export default router;

package/api/src/routes/health.ts

@@ -38,7 +38,7 @@ router.get('/', async (_req, res) => {
         environment: config.nodeEnv,
         services: {
             database: dbStatus,
-            llm: config.llm.apiKey ? 'configured' : 'not_configured',
+            llm: 'realtimex_sdk', // Managed by RealTimeX SDK
             gmail: config.gmail.clientId ? 'configured' : 'not_configured',
             microsoft: config.microsoft.clientId ? 'configured' : 'not_configured',
         },

package/api/src/routes/index.ts

@@ -8,11 +8,15 @@ import settingsRoutes from './settings.js';
 import emailsRoutes from './emails.js';
 import migrateRoutes from './migrate.js';
 import sdkRoutes from './sdk.js';
+import ttsRoutes from './tts.js';
+import agentRoutes from './agent.js';
 import rulePacksRoutes from './rulePacks.js';
 import draftsRoutes from './drafts.js';
 
+
 const router = Router();
 
+
 router.use('/health', healthRoutes);
 router.use('/auth', authRoutes);
 router.use('/sync', syncRoutes);
@@ -22,7 +26,10 @@ router.use('/settings', settingsRoutes);
 router.use('/emails', emailsRoutes);
 router.use('/migrate', migrateRoutes);
 router.use('/sdk', sdkRoutes);
+router.use('/tts', ttsRoutes);
+router.use('/agent', agentRoutes);
 router.use('/rule-packs', rulePacksRoutes);
 router.use('/drafts', draftsRoutes);
 
+
 export default router;

package/api/src/routes/migrate.ts

@@ -13,7 +13,7 @@ const logger = createLogger('MigrateRoutes');
 router.post('/',
     validateBody(schemas.migrate),
     asyncHandler(async (req, res) => {
-        const { projectRef, accessToken } = req.body;
+        const { projectRef, accessToken, anonKey } = req.body;
 
         logger.info('Starting migration', { projectRef });
 
@@ -30,10 +30,17 @@ router.post('/',
 
             const scriptPath = join(config.scriptsDir, 'migrate.sh');
 
+            // Construct Supabase URL from project ref
+            const supabaseUrl = `https://${projectRef}.supabase.co`;
+
             const env = {
                 ...process.env,
                 SUPABASE_PROJECT_ID: projectRef,
                 SUPABASE_ACCESS_TOKEN: accessToken || '',
+                SUPABASE_URL: supabaseUrl,
+                // Note: migrate.sh will fetch SERVICE_ROLE_KEY using access token
+                // anonKey provided as fallback if API fetch fails
+                SUPABASE_ANON_KEY: anonKey || '',
                 SKIP_FUNCTIONS: '0',
             };
 

package/api/src/routes/tts.ts

@@ -0,0 +1,187 @@
+import { Request, Response, Router } from 'express';
+import { SDKService } from '../services/SDKService.js';
+
+const router = Router();
+
+/**
+ * GET /api/tts/providers
+ * List available TTS providers and their configuration options
+ */
+router.get('/providers', async (req: Request, res: Response) => {
+    try {
+        const sdk = SDKService.getSDK();
+        if (!sdk) {
+            return res.status(503).json({
+                success: false,
+                error: 'RealTimeX SDK not available. Please ensure RealTimeX Desktop is running.'
+            });
+        }
+
+        // Check if TTS module is available
+        if (!sdk.tts) {
+            return res.status(503).json({
+                success: false,
+                error: 'TTS module not available. Please ensure RealTimeX Desktop is running and updated to v1.2.3+.'
+            });
+        }
+
+        const providers = await sdk.tts.listProviders();
+
+        res.json({
+            success: true,
+            providers
+        });
+    } catch (error: any) {
+        console.error('[TTS API] Failed to list providers:', error);
+        res.status(503).json({
+            success: false,
+            error: error.message || 'Failed to list TTS providers. Ensure RealTimeX Desktop is running.'
+        });
+    }
+});
+
+/**
+ * POST /api/tts/speak
+ * Generate full audio buffer for text
+ * Body: { text: string, provider?: string, voice?: string, speed?: number }
+ */
+router.post('/speak', async (req: Request, res: Response) => {
+    try {
+        const { text, provider, voice, speed, quality } = req.body;
+
+        console.log('[TTS API] Received TTS request:', { text: text?.substring(0, 50) + '...', provider, voice, speed, quality });
+
+        if (!text || typeof text !== 'string') {
+            return res.status(400).json({
+                success: false,
+                error: 'Text is required'
+            });
+        }
+
+        const sdk = SDKService.getSDK();
+        if (!sdk) {
+            return res.status(503).json({
+                success: false,
+                error: 'RealTimeX SDK not available'
+            });
+        }
+
+        // Check if TTS module is available
+        if (!sdk.tts) {
+            return res.status(503).json({
+                success: false,
+                error: 'TTS module not available. Please ensure RealTimeX Desktop is running and updated to v1.2.3+.'
+            });
+        }
+
+        const options: any = {};
+        if (provider) options.provider = provider;
+        if (voice) options.voice = voice;
+        if (speed) options.speed = parseFloat(speed);
+        if (quality) options.num_inference_steps = parseInt(quality);
+
+        console.log('[TTS API] Calling SDK with options:', options);
+        const audioBuffer = await sdk.tts.speak(text, options);
+
+        // Return audio as binary
+        res.setHeader('Content-Type', 'audio/mpeg');
+        res.send(Buffer.from(audioBuffer));
+    } catch (error: any) {
+        console.error('[TTS API] Failed to generate speech:', error);
+        res.status(500).json({
+            success: false,
+            error: error.message || 'Failed to generate speech'
+        });
+    }
+});
+
+/**
+ * POST /api/tts/stream
+ * Stream audio chunks via Server-Sent Events
+ * Body: { text: string, provider?: string, voice?: string, speed?: number }
+ */
+router.post('/stream', async (req: Request, res: Response) => {
+    try {
+        const { text, provider, voice, speed, quality } = req.body;
+
+        if (!text || typeof text !== 'string') {
+            return res.status(400).json({
+                success: false,
+                error: 'Text is required'
+            });
+        }
+
+        const sdk = SDKService.getSDK();
+        if (!sdk) {
+            return res.status(503).json({
+                success: false,
+                error: 'RealTimeX SDK not available'
+            });
+        }
+
+        // Check if TTS module is available
+        if (!sdk.tts) {
+            return res.status(503).json({
+                success: false,
+                error: 'TTS module not available. Please ensure RealTimeX Desktop is running and updated to v1.2.3+.'
+            });
+        }
+
+        // Set up SSE
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+
+        const options: any = {};
+        if (provider) options.provider = provider;
+        if (voice) options.voice = voice;
+        if (speed) options.speed = parseFloat(speed);
+        if (quality) options.num_inference_steps = parseInt(quality);
+
+        // Send info event
+        res.write(`event: info\n`);
+        res.write(`data: ${JSON.stringify({ message: 'Starting TTS generation...' })}\n\n`);
+
+        try {
+            // Stream chunks
+            for await (const chunk of sdk.tts.speakStream(text, options)) {
+                // Encode ArrayBuffer to base64
+                const base64Audio = Buffer.from(chunk.audio).toString('base64');
+
+                res.write(`event: chunk\n`);
+                res.write(`data: ${JSON.stringify({
+                    index: chunk.index,
+                    total: chunk.total,
+                    audio: base64Audio,
+                    mimeType: chunk.mimeType
+                })}\n\n`);
+            }
+
+            // Send done event
+            res.write(`event: done\n`);
+            res.write(`data: ${JSON.stringify({ message: 'TTS generation complete' })}\n\n`);
+        } catch (streamError: any) {
+            res.write(`event: error\n`);
+            res.write(`data: ${JSON.stringify({ error: streamError.message })}\n\n`);
+        }
+
+        res.end();
+    } catch (error: any) {
+        console.error('[TTS API] Failed to stream speech:', error);
+
+        // If headers not sent yet, send JSON error
+        if (!res.headersSent) {
+            res.status(500).json({
+                success: false,
+                error: error.message || 'Failed to stream speech'
+            });
+        } else {
+            // Send SSE error event
+            res.write(`event: error\n`);
+            res.write(`data: ${JSON.stringify({ error: error.message })}\n\n`);
+            res.end();
+        }
+    }
+});
+
+export default router;