@ema.co/mcp-toolkit 1.5.1 → 1.6.0

package/dist/sdk/workflow-intent.js

@@ -550,7 +550,7 @@ export function parseNaturalLanguage(text) {
             });
         }
     }
-    // Detect tools
+    // Detect tools from text
     const tools = [];
     for (const { pattern, namespace, action } of TOOL_PATTERNS) {
         if (pattern.test(text)) {
@@ -1297,8 +1297,9 @@ export function summarizeIntentConfidence(confidence) {
 export function intentToSpec(intent) {
     const nodes = [];
     const resultMappings = [];
-    // 1. Add trigger
+    // 1. Add trigger - Voice and Chat both use chat_trigger, Dashboard uses document_trigger
     const triggerId = "trigger";
+    // Note: voice_trigger doesn't exist in API - Voice AI uses chat_trigger with voiceSettings in proto_config
     const triggerType = intent.persona_type === "dashboard" ? "document_trigger" : "chat_trigger";
     nodes.push({
         id: triggerId,
@@ -1349,6 +1350,11 @@ export function intentToSpec(intent) {
                     actionName: triggerId,
                     output: "user_query",
                 },
+                // REQUIRED: Widget binding to fileUpload data sources (uses multiBinding.elements format)
+                datastore_configs: {
+                    type: "widget_config_array",
+                    widgetNames: ["fileUpload"],
+                },
             },
         });
     }
@@ -1370,26 +1376,13 @@ export function intentToSpec(intent) {
         });
     }
     // 5. Add tool caller if tools defined
-    let toolCallerId;
-    if (intent.tools && intent.tools.length > 0) {
-        toolCallerId = "tool_caller";
-        nodes.push({
-            id: toolCallerId,
-            actionType: "external_action_caller",
-            displayName: "External Actions",
-            inputs: {
-                conversation: {
-                    type: "action_output",
-                    actionName: triggerId,
-                    output: "chat_conversation",
-                },
-            },
-            tools: intent.tools.map((t) => ({
-                name: t.action,
-                namespace: t.namespace,
-            })),
-        });
-    }
+    // DISABLED: external_action_caller format causes 500 errors
+    // TODO: Fix tool format and re-enable - tools are stored in intent for future use
+    const toolCallerId = undefined;
+    // if (intent.tools && intent.tools.length > 0) {
+    //   toolCallerId = "tool_caller";
+    //   nodes.push({...});
+    // }
     // 6. Add HITL if required
     let hitlId;
     if (intent.constraints?.require_hitl && toolCallerId) {
@@ -1415,9 +1408,16 @@ export function intentToSpec(intent) {
             actionName: triggerId,
             output: "user_query",
         },
+        // REQUIRED: Widget binding to fusionModel for LLM selection
+        model_config: {
+            type: "widget_config",
+            widgetName: "fusionModel",
+        },
     };
     if (searchId) {
-        respondInputs.search_results = {
+        // call_llm uses "named_inputs" not "search_results"
+        // (respond_with_sources doesn't exist in API - mapped to call_llm)
+        respondInputs.named_inputs = {
             type: "action_output",
             actionName: searchId,
             output: "search_results",
@@ -1425,7 +1425,8 @@ export function intentToSpec(intent) {
     }
     nodes.push({
         id: respondId,
-        actionType: searchId ? "respond_with_sources" : "call_llm",
+        // respond_with_sources doesn't exist in API - always use call_llm
+        actionType: "call_llm",
         displayName: "Response",
         inputs: respondInputs,
     });
@@ -1433,12 +1434,27 @@ export function intentToSpec(intent) {
         nodeId: respondId,
         output: searchId ? "response_with_sources" : "response_with_sources",
     });
+    // NOTE: Action chains (email_with_validation, doc_to_email, etc.) are NOT processed here.
+    // Complex workflows with action chains should be generated via LLM using:
+    // 1. generateWorkflowPrompt(intent, availableActions) - builds LLM prompt
+    // 2. Pass to Auto Builder or external LLM
+    // 3. Parse the LLM response as WorkflowSpec
+    // This keeps intentToSpec simple (basic RAG workflow) and lets LLM handle complexity.
+    // Build voiceConfig from intent.voice_config
+    const voiceConfig = intent.persona_type === "voice" ? {
+        welcomeMessage: intent.voice_config?.welcome_message,
+        identityAndPurpose: intent.voice_config?.identity ?? intent.description,
+        hangupInstructions: intent.voice_config?.hangup_instructions,
+        // Additional fields can be extracted from intent description in the future
+    } : undefined;
     return {
         name: intent.name,
         description: intent.description,
         personaType: intent.persona_type,
         nodes,
         resultMappings,
+        ...(voiceConfig && { voiceConfig }),
+        ...(intent.persona_type === "chat" && { chatConfig: { name: intent.name } }),
     };
 }
 export function parseInput(input) {
@@ -1583,3 +1599,209 @@ export function generateContentInstructions(semantics) {
     }
     return instructions.join("\n");
 }
+/**
+ * Determine if intent requires LLM-driven generation or can use simple intentToSpec.
+ *
+ * Simple (use intentToSpec):
+ * - Basic Q&A with search
+ * - Single intent without delivery
+ *
+ * Complex (use LLM):
+ * - Action chains (email, document generation)
+ * - Multiple intents with routing
+ * - HITL requirements
+ * - External tool calls
+ */
+export function needsLLMGeneration(intent) {
+    // Check for action chains
+    if (intent.action_chains && intent.action_chains.length > 0) {
+        return true;
+    }
+    // Check for email/document delivery
+    if (intent.delivery_config?.methods?.some(m => m.type === "email" || m.type === "document")) {
+        return true;
+    }
+    // Check for HITL requirements
+    if (intent.constraints?.require_hitl) {
+        return true;
+    }
+    // Check for multiple intents (needs categorizer with complex routing)
+    if (intent.intents && intent.intents.length > 2) {
+        return true;
+    }
+    // Check for tools/external actions
+    if (intent.tools && intent.tools.length > 0) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Generate a workflow spec or LLM prompt based on intent complexity.
+ *
+ * For simple intents: returns spec directly
+ * For complex intents: returns LLM prompt with full context
+ *
+ * @param intent - Parsed workflow intent
+ * @param availableActions - Actions from ListActions API (optional)
+ * @returns Generation result with either spec or LLM prompt
+ */
+export function generateWorkflow(intent, availableActions) {
+    const complexity = {
+        has_action_chains: !!(intent.action_chains && intent.action_chains.length > 0),
+        has_email: !!(intent.delivery_config?.methods?.some(m => m.type === "email")),
+        has_hitl: !!intent.constraints?.require_hitl,
+        has_multi_intent: !!(intent.intents && intent.intents.length > 2),
+        chain_ids: intent.action_chains?.map(c => c.id) ?? [],
+    };
+    // Simple workflow - use intentToSpec
+    if (!needsLLMGeneration(intent)) {
+        return {
+            needs_llm: false,
+            spec: intentToSpec(intent),
+            reason: "Simple workflow (basic RAG pattern) - no LLM needed",
+            complexity,
+        };
+    }
+    // Complex workflow - generate LLM prompt
+    const systemPrompt = buildWorkflowGenerationSystemPrompt(availableActions);
+    const userPrompt = buildWorkflowGenerationUserPrompt(intent);
+    return {
+        needs_llm: true,
+        llm_prompt: {
+            system: systemPrompt,
+            user: userPrompt,
+        },
+        reason: `Complex workflow requires LLM: ${complexity.chain_ids.length > 0 ? `chains: ${complexity.chain_ids.join(', ')}` : ''} ${complexity.has_email ? 'email' : ''} ${complexity.has_hitl ? 'HITL' : ''}`.trim(),
+        complexity,
+    };
+}
+/**
+ * Build system prompt for LLM workflow generation.
+ */
+function buildWorkflowGenerationSystemPrompt(availableActions) {
+    const actionList = availableActions
+        ? availableActions.map(a => `- ${a.name}: ${a.description} (inputs: ${a.inputs.join(', ')})`).join('\n')
+        : 'Use standard Ema actions: chat_trigger, search, call_llm, entity_extraction, general_hitl, send_email, chat_categorizer';
+    return `You are an expert workflow designer for the Ema AI platform.
+
+Your task is to generate a WorkflowSpec JSON that implements the user's requirements.
+
+## Available Actions
+${actionList}
+
+## WorkflowSpec Schema
+\`\`\`typescript
+interface WorkflowSpec {
+  name: string;
+  description: string;
+  personaType: "voice" | "chat" | "dashboard";
+  nodes: Node[];
+  resultMappings: { nodeId: string; output: string }[];
+}
+
+interface Node {
+  id: string;                    // Unique identifier (snake_case)
+  actionType: string;            // Action name from available actions
+  displayName: string;           // Human-readable name
+  inputs?: Record<string, InputBinding>;
+  runIf?: { actionName: string; output: string; enumValue: string };  // Conditional execution
+  categories?: Category[];       // For categorizer nodes
+}
+
+interface InputBinding {
+  type: "action_output" | "inline_string" | "widget_config";
+  actionName?: string;           // For action_output
+  output?: string;               // For action_output
+  value?: string;                // For inline_string
+  widgetName?: string;           // For widget_config
+}
+\`\`\`
+
+## Critical Rules
+1. ALWAYS start with a trigger node (chat_trigger for voice/chat, document_trigger for dashboard)
+2. Wire data correctly: each input must reference a valid upstream output
+3. For EMAIL: extract recipient via entity_extraction FIRST, add HITL before send_email
+4. Use runIf for conditional execution (after HITL approval)
+5. All email recipients must come from entity_extraction, NOT from LLM-generated text
+
+## Example: Email with HITL
+\`\`\`json
+{
+  "nodes": [
+    { "id": "trigger", "actionType": "chat_trigger", "displayName": "Trigger" },
+    { "id": "extract", "actionType": "entity_extraction", "displayName": "Extract Email", 
+      "inputs": { "conversation": { "type": "action_output", "actionName": "trigger", "output": "chat_conversation" } } },
+    { "id": "respond", "actionType": "call_llm", "displayName": "Generate Response",
+      "inputs": { "query": { "type": "action_output", "actionName": "trigger", "output": "user_query" } } },
+    { "id": "hitl", "actionType": "general_hitl", "displayName": "Approve Email",
+      "inputs": { "query": { "type": "action_output", "actionName": "respond", "output": "response" } } },
+    { "id": "send_email", "actionType": "send_email", "displayName": "Send Email",
+      "inputs": { 
+        "email_to": { "type": "action_output", "actionName": "extract", "output": "email_address" },
+        "email_body": { "type": "action_output", "actionName": "respond", "output": "response" }
+      },
+      "runIf": { "actionName": "hitl", "output": "hitl_status", "enumValue": "HITL Success" } }
+  ],
+  "resultMappings": [{ "nodeId": "send_email", "output": "email_sent" }]
+}
+\`\`\`
+
+Respond with ONLY valid JSON - no markdown, no explanation.`;
+}
+/**
+ * Build user prompt with intent details.
+ */
+function buildWorkflowGenerationUserPrompt(intent) {
+    const sections = [];
+    sections.push(`## User Request\n${intent.description}`);
+    sections.push(`## Persona Type\n${intent.persona_type ?? 'chat'}`);
+    if (intent.action_chains && intent.action_chains.length > 0) {
+        sections.push(`## Detected Patterns\n${intent.action_chains.map(c => `- ${c.name}: ${c.description}`).join('\n')}`);
+    }
+    if (intent.intents && intent.intents.length > 0) {
+        sections.push(`## User Intents\n${intent.intents.map(i => `- ${i.name}: ${i.description}`).join('\n')}`);
+    }
+    if (intent.entities && intent.entities.length > 0) {
+        sections.push(`## Entities to Extract\n${intent.entities.map(e => `- ${e.name}: ${e.type}`).join('\n')}`);
+    }
+    if (intent.data_sources && intent.data_sources.length > 0) {
+        sections.push(`## Data Sources\n${intent.data_sources.map(d => `- ${d.type}${d.instructions ? `: ${d.instructions}` : ''}`).join('\n')}`);
+    }
+    if (intent.constraints) {
+        const constraints = [];
+        if (intent.constraints.require_hitl)
+            constraints.push('- Require human approval before side effects');
+        if (intent.constraints.require_validation)
+            constraints.push('- Require validation before actions');
+        if (intent.constraints.enable_web_search)
+            constraints.push('- Enable web search');
+        if (constraints.length > 0) {
+            sections.push(`## Constraints\n${constraints.join('\n')}`);
+        }
+    }
+    sections.push('\nGenerate a WorkflowSpec JSON that implements this workflow.');
+    return sections.join('\n\n');
+}
+/**
+ * Parse LLM response into WorkflowSpec.
+ * Handles markdown code blocks and validates structure.
+ */
+export function parseWorkflowSpecFromLLM(llmResponse) {
+    try {
+        // Extract JSON from markdown code block if present
+        let json = llmResponse;
+        const codeBlockMatch = llmResponse.match(/```(?:json)?\s*([\s\S]*?)```/);
+        if (codeBlockMatch) {
+            json = codeBlockMatch[1];
+        }
+        const parsed = JSON.parse(json.trim());
+        // Basic validation
+        if (!parsed.nodes || !Array.isArray(parsed.nodes)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}