@ema.co/mcp-toolkit 1.4.3 → 1.5.0

package/dist/sdk/workflow-transformer.js

@@ -0,0 +1,600 @@
+/**
+ * Workflow Transformer
+ *
+ * The LLM-native approach to workflow manipulation:
+ * 1. Decompile raw workflow_def to typed WorkflowSpec
+ * 2. Expose schema for LLM context
+ * 3. LLM transforms the spec directly
+ * 4. Compile back to workflow_def
+ *
+ * WHY THIS APPROACH:
+ * - LLMs excel at structured data transformation
+ * - Type definitions serve as schema documentation
+ * - Validation happens at compile time
+ * - No brittle keyword matching
+ */
+import { compileWorkflow } from "./workflow-generator.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// SCHEMA DOCUMENTATION FOR LLM CONTEXT
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * This schema is designed to be included in LLM context.
+ * The LLM reads this, understands the structure, and outputs valid specs.
+ */
+export const WORKFLOW_SCHEMA_FOR_LLM = `
+# Ema Workflow Schema
+
+## Overview
+Workflows are defined as a WorkflowSpec object with nodes and connections.
+Each node has typed inputs/outputs. Connections are defined via InputBinding.
+
+## Core Types
+
+### WorkflowSpec
+\`\`\`typescript
+interface WorkflowSpec {
+  name: string;                    // Workflow identifier
+  description: string;             // What this workflow does
+  personaType: "voice" | "chat" | "dashboard";
+  nodes: Node[];                   // All workflow nodes
+  resultMappings: ResultMapping[]; // Which outputs go to WORKFLOW_OUTPUT
+}
+\`\`\`
+
+### Node
+\`\`\`typescript
+interface Node {
+  id: string;                      // Unique node identifier (e.g., "search_1", "categorizer_main")
+  actionType: ActionType;          // Node type (see ActionType below)
+  displayName: string;             // Human-readable name
+  description?: string;            // What this node does
+  inputs?: Record<string, InputBinding>;  // Input connections
+  runIf?: RunIfCondition;          // Conditional execution
+  categories?: Category[];         // For categorizer nodes only
+  tools?: Tool[];                  // For custom_agent nodes
+  disableHitl?: boolean;          // Skip human-in-the-loop
+}
+\`\`\`
+
+### ActionType (Available Node Types)
+\`\`\`typescript
+type ActionType =
+  // Triggers (entry points)
+  | "chat_trigger"           // Chat/voice entry point
+  | "document_trigger"       // Document upload entry point
+  
+  // Routing (categorization)
+  | "chat_categorizer"       // Categorizes chat conversation
+  | "text_categorizer"       // Categorizes text
+  
+  // Search (retrieval)
+  | "search"                 // Knowledge base search
+  | "live_web_search"        // Real-time web search
+  | "combine_search_results" // Merge multiple searches
+  | "conversation_to_search_query"  // Summarize conversation for search
+  
+  // Generation (LLM responses)
+  | "respond_with_sources"   // RAG response with citations
+  | "call_llm"               // Custom LLM generation
+  | "fixed_response"         // Template response (no LLM)
+  
+  // Entity extraction
+  | "entity_extraction"      // Extract structured data from text
+  
+  // External actions
+  | "external_action_caller" // Call APIs (Salesforce, ServiceNow, etc.)
+  | "send_email_agent"       // Send email
+  
+  // Human-in-the-loop
+  | "general_hitl"           // Human approval step
+  
+  // Validation
+  | "response_validator";    // Validate LLM output
+\`\`\`
+
+### InputBinding (How Nodes Connect)
+\`\`\`typescript
+interface InputBinding {
+  type: "action_output" | "inline_string" | "inline_number" | "inline_bool" | "widget_config" | "llm_inferred";
+  
+  // For action_output (connecting nodes):
+  actionName?: string;       // Source node ID
+  output?: string;           // Source output name
+  
+  // For inline values:
+  value?: string | number | boolean;
+  
+  // For widget config (persona settings):
+  widgetName?: string;
+  
+  // For call_llm named inputs:
+  namedInputs?: Array<{ name: string; binding: InputBinding }>;
+}
+\`\`\`
+
+### Common Input/Output Names
+
+#### trigger (chat_trigger)
+- Outputs: user_query, chat_conversation
+
+#### categorizer (chat_categorizer, text_categorizer)
+- Inputs: text (the text to categorize)
+- Outputs: category (the selected category as enum)
+
+#### search
+- Inputs: query (search query text)
+- Outputs: search_results (SEARCH_RESULT type)
+
+#### call_llm
+- Inputs: query, instructions, named_inputs (for additional context)
+- Outputs: response_with_sources (TEXT_WITH_SOURCES type)
+
+#### respond_with_sources
+- Inputs: query, search_results
+- Outputs: response_with_sources (TEXT_WITH_SOURCES type)
+
+#### entity_extraction
+- Inputs: text_input, extraction_columns (schema)
+- Outputs: extracted_entities (structured data)
+
+#### send_email_agent
+- Inputs: to_email, subject, email_body, sender_email
+- Outputs: email_result
+
+#### general_hitl
+- Inputs: summary (what to approve)
+- Outputs: approval_decision (approve/reject enum)
+
+### RunIfCondition (Conditional Execution)
+\`\`\`typescript
+interface RunIfCondition {
+  sourceAction: string;    // Node ID to check
+  sourceOutput: string;    // Output to compare
+  operator: "eq" | "neq";  // Comparison operator
+  value: string;           // Expected value (category name for categorizers)
+}
+\`\`\`
+
+### Category (For Categorizers)
+\`\`\`typescript
+interface Category {
+  name: string;            // Category identifier (e.g., "billing_inquiry")
+  description: string;     // When this category applies
+  examples?: string[];     // Example user inputs
+}
+\`\`\`
+
+### ResultMapping (WORKFLOW_OUTPUT)
+\`\`\`typescript
+interface ResultMapping {
+  nodeId: string;          // Which node's output to expose
+  output: string;          // Which output (usually "response_with_sources")
+}
+\`\`\`
+
+## Common Patterns
+
+### RAG Pattern (Search + Generate)
+\`\`\`typescript
+nodes: [
+  { id: "trigger", actionType: "chat_trigger", displayName: "Trigger" },
+  { id: "search_1", actionType: "search", displayName: "Knowledge Search",
+    inputs: { query: { type: "action_output", actionName: "trigger", output: "user_query" } }
+  },
+  { id: "respond", actionType: "respond_with_sources", displayName: "Generate Response",
+    inputs: {
+      query: { type: "action_output", actionName: "trigger", output: "user_query" },
+      search_results: { type: "action_output", actionName: "search_1", output: "search_results" }
+    }
+  }
+]
+\`\`\`
+
+### Intent Routing Pattern
+\`\`\`typescript
+nodes: [
+  { id: "trigger", actionType: "chat_trigger", displayName: "Trigger" },
+  { id: "categorizer", actionType: "chat_categorizer", displayName: "Intent Router",
+    inputs: { text: { type: "action_output", actionName: "trigger", output: "user_query" } },
+    categories: [
+      { name: "billing", description: "Questions about bills, payments, invoices" },
+      { name: "technical", description: "Technical support issues" },
+      { name: "Fallback", description: "Unclear or general questions" }
+    ]
+  },
+  { id: "billing_response", actionType: "call_llm", displayName: "Billing Handler",
+    runIf: { sourceAction: "categorizer", sourceOutput: "category", operator: "eq", value: "billing" },
+    inputs: { 
+      query: { type: "action_output", actionName: "trigger", output: "user_query" },
+      instructions: { type: "inline_string", value: "Help with billing inquiries..." }
+    }
+  }
+]
+\`\`\`
+
+### Email with HITL Pattern
+\`\`\`typescript
+nodes: [
+  { id: "extract_email", actionType: "entity_extraction", displayName: "Extract Email",
+    inputs: { text_input: { type: "action_output", actionName: "summarizer", output: "summarized_conversation" } }
+  },
+  { id: "approval", actionType: "general_hitl", displayName: "Confirm Email",
+    inputs: { summary: { type: "inline_string", value: "Ready to send email. Approve?" } }
+  },
+  { id: "send_email", actionType: "send_email_agent", displayName: "Send Email",
+    runIf: { sourceAction: "approval", sourceOutput: "approval_decision", operator: "eq", value: "approve" },
+    inputs: {
+      to_email: { type: "action_output", actionName: "extract_email", output: "extracted_entities" },
+      email_body: { type: "action_output", actionName: "body_generator", output: "fixed_response_with_sources" }
+    }
+  }
+]
+\`\`\`
+
+## Transformation Rules
+
+### Rewiring a Connection
+To change where a node gets its input:
+1. Find the node in the nodes array
+2. Update the InputBinding for the target input
+3. Change actionName/output to point to new source
+
+Example: Change \`send_email.to_email\` from \`llm_extractor\` to \`entity_extraction\`:
+\`\`\`typescript
+// Before:
+inputs: { to_email: { type: "action_output", actionName: "llm_extractor", output: "response_with_sources" } }
+
+// After:
+inputs: { to_email: { type: "action_output", actionName: "entity_extraction", output: "extracted_entities" } }
+\`\`\`
+
+### Adding HITL Before an Action
+1. Create a new general_hitl node with unique ID
+2. Add runIf condition to the target node checking HITL approval
+3. Ensure HITL summary describes what's being approved
+
+### Removing a Node
+1. Remove the node from the nodes array
+2. Update any nodes that referenced it to use alternative source
+3. Remove from resultMappings if present
+
+### Adding a Category
+1. Find the categorizer node
+2. Add to the categories array
+3. Add a handler node with runIf condition for the new category
+`;
+// ═══════════════════════════════════════════════════════════════════════════
+// DECOMPILER: workflow_def JSON → WorkflowSpec
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Decompile a raw workflow_def JSON back to a typed WorkflowSpec.
+ * This allows LLM to work with clean typed objects instead of raw JSON.
+ */
+export function decompileWorkflow(workflowDef, personaType = "chat") {
+    const actions = (workflowDef.actions || []);
+    const results = (workflowDef.results || {});
+    const enumTypes = (workflowDef.enumTypes || []);
+    // Build enum lookup for category extraction
+    const enumLookup = new Map();
+    for (const et of enumTypes) {
+        const name = et.name?.name?.name;
+        const options = (et.options || []);
+        if (name) {
+            enumLookup.set(name, options.map(o => ({
+                name: o.name,
+                description: o.description,
+                examples: o.examples,
+            })));
+        }
+    }
+    // Decompile each action to a Node
+    const nodes = actions.map(action => decompileAction(action, enumLookup));
+    // Decompile result mappings
+    const resultMappings = Object.values(results).map(r => ({
+        nodeId: r.actionName,
+        output: r.outputName,
+    }));
+    return {
+        name: extractWorkflowName(workflowDef),
+        description: workflowDef.description || "",
+        personaType,
+        nodes,
+        resultMappings,
+    };
+}
+function extractWorkflowName(workflowDef) {
+    const wn = workflowDef.workflowName;
+    if (wn?.name?.namespaces?.[2]) {
+        return wn.name.namespaces[2]; // persona ID
+    }
+    return workflowDef.displayName || "workflow";
+}
+function decompileAction(action, enumLookup) {
+    const actionDef = action.action;
+    const actionName = actionDef?.name?.name || "unknown";
+    const displaySettings = action.displaySettings;
+    const inputs = (action.inputs || {});
+    const runIf = action.runIf;
+    const typeArgs = action.typeArguments;
+    // Map raw action name to ActionType
+    const actionType = mapToActionType(actionName);
+    // Decompile inputs
+    const decompInputs = {};
+    for (const [key, value] of Object.entries(inputs)) {
+        const binding = decompileBinding(value);
+        if (binding) {
+            decompInputs[key] = binding;
+        }
+    }
+    // Decompile runIf
+    let decompRunIf;
+    if (runIf) {
+        decompRunIf = decompileRunIf(runIf);
+    }
+    // Get categories for categorizers
+    let categories;
+    if (actionType.includes("categorizer") && typeArgs?.categories?.enumType?.name?.name) {
+        categories = enumLookup.get(typeArgs.categories.enumType.name.name);
+    }
+    return {
+        id: action.name,
+        actionType,
+        displayName: displaySettings?.displayName || action.name,
+        description: displaySettings?.description,
+        inputs: Object.keys(decompInputs).length > 0 ? decompInputs : undefined,
+        runIf: decompRunIf,
+        categories,
+        disableHitl: action.disableHumanInteraction,
+    };
+}
+function mapToActionType(rawName) {
+    const mapping = {
+        chat_trigger: "chat_trigger",
+        document_trigger: "document_trigger",
+        chat_categorizer: "chat_categorizer",
+        text_categorizer: "text_categorizer",
+        conversation_to_search_query: "conversation_to_search_query",
+        search: "search",
+        live_web_search: "live_web_search",
+        combine_search_results: "combine_search_results",
+        respond_with_sources: "respond_with_sources",
+        call_llm: "call_llm",
+        fixed_response: "fixed_response",
+        entity_extraction: "entity_extraction",
+        entity_extraction_with_documents: "entity_extraction",
+        external_action_caller: "external_action_caller",
+        send_email_agent: "send_email_agent",
+        general_hitl: "general_hitl",
+        hitl: "general_hitl",
+        response_validator: "response_validator",
+    };
+    return mapping[rawName] || "call_llm";
+}
+function decompileBinding(value) {
+    const v = value;
+    // Action output binding
+    if (v.actionOutput) {
+        const ao = v.actionOutput;
+        return {
+            type: "action_output",
+            actionName: ao.actionName,
+            output: ao.output,
+        };
+    }
+    // Widget config binding
+    if (v.widgetConfig) {
+        const wc = v.widgetConfig;
+        return {
+            type: "widget_config",
+            widgetName: wc.widgetName,
+        };
+    }
+    // Inline value binding
+    if (v.inline) {
+        const inline = v.inline;
+        if (inline.wellKnown?.stringValue !== undefined) {
+            return {
+                type: "inline_string",
+                value: inline.wellKnown.stringValue,
+            };
+        }
+        if (inline.wellKnown?.boolValue !== undefined) {
+            return {
+                type: "inline_bool",
+                value: inline.wellKnown.boolValue,
+            };
+        }
+        if (inline.wellKnown?.int64Value !== undefined) {
+            return {
+                type: "inline_number",
+                value: parseInt(inline.wellKnown.int64Value, 10),
+            };
+        }
+        if (inline.enumValue) {
+            return {
+                type: "inline_string",
+                value: inline.enumValue,
+            };
+        }
+    }
+    // Multi-binding (named inputs)
+    if (v.multiBinding) {
+        const mb = v.multiBinding;
+        const namedInputs = [];
+        for (const elem of mb.elements || []) {
+            if (elem.namedBinding?.name && elem.namedBinding.value) {
+                const binding = decompileBinding(elem.namedBinding.value);
+                if (binding) {
+                    namedInputs.push({ name: elem.namedBinding.name, binding });
+                }
+            }
+        }
+        if (namedInputs.length > 0) {
+            return {
+                type: "action_output", // Container type
+                namedInputs,
+            };
+        }
+    }
+    return null;
+}
+function decompileRunIf(runIf) {
+    const lhs = runIf.lhs;
+    const rhs = runIf.rhs;
+    const operator = runIf.operator;
+    if (!lhs?.actionOutput || !rhs?.inline?.enumValue)
+        return undefined;
+    const opMap = {
+        1: "eq",
+        2: "neq",
+        3: "gt",
+        4: "lt",
+        5: "gte",
+        6: "lte",
+    };
+    return {
+        sourceAction: lhs.actionOutput.actionName || "",
+        sourceOutput: lhs.actionOutput.output || "",
+        operator: opMap[operator] || "eq",
+        value: rhs.inline.enumValue,
+    };
+}
+/**
+ * Transform a workflow using an LLM-generated spec modification.
+ *
+ * The expected workflow:
+ * 1. Decompile existing workflow to WorkflowSpec
+ * 2. LLM reads spec + schema + user request
+ * 3. LLM outputs modified WorkflowSpec (or a diff/patch)
+ * 4. This function compiles back to workflow_def
+ *
+ * @param originalDef - The original workflow_def JSON
+ * @param modifiedSpec - The LLM-modified WorkflowSpec
+ * @returns TransformResult with compiled workflow
+ */
+export function transformWorkflow(originalDef, modifiedSpec) {
+    const changes = [];
+    const errors = [];
+    try {
+        // Compile the modified spec
+        const compiled = compileWorkflow(modifiedSpec);
+        // Preserve workflowName from original (important for deployment)
+        compiled.workflow_def.workflowName = originalDef.workflowName;
+        // Detect what changed
+        const originalSpec = decompileWorkflow(originalDef, modifiedSpec.personaType);
+        changes.push(...detectChanges(originalSpec, modifiedSpec));
+        return {
+            success: true,
+            spec: modifiedSpec,
+            workflow_def: compiled.workflow_def,
+            changes,
+            errors,
+        };
+    }
+    catch (e) {
+        errors.push(`Compilation failed: ${e instanceof Error ? e.message : String(e)}`);
+        return {
+            success: false,
+            spec: modifiedSpec,
+            workflow_def: originalDef,
+            changes,
+            errors,
+        };
+    }
+}
+function detectChanges(original, modified) {
+    const changes = [];
+    const originalIds = new Set(original.nodes.map(n => n.id));
+    const modifiedIds = new Set(modified.nodes.map(n => n.id));
+    // Added nodes
+    for (const id of modifiedIds) {
+        if (!originalIds.has(id)) {
+            changes.push(`Added node: ${id}`);
+        }
+    }
+    // Removed nodes
+    for (const id of originalIds) {
+        if (!modifiedIds.has(id)) {
+            changes.push(`Removed node: ${id}`);
+        }
+    }
+    // Modified nodes (simplified check)
+    for (const modNode of modified.nodes) {
+        const origNode = original.nodes.find(n => n.id === modNode.id);
+        if (origNode) {
+            // Check if inputs changed
+            const origInputs = JSON.stringify(origNode.inputs || {});
+            const modInputs = JSON.stringify(modNode.inputs || {});
+            if (origInputs !== modInputs) {
+                changes.push(`Modified ${modNode.id} inputs`);
+            }
+            // Check if runIf changed
+            if (JSON.stringify(origNode.runIf) !== JSON.stringify(modNode.runIf)) {
+                changes.push(`Modified ${modNode.id} runIf condition`);
+            }
+        }
+    }
+    return changes;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPERS FOR LLM CONTEXT
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Generate a summary of a workflow for LLM context.
+ */
+export function summarizeSpec(spec) {
+    const lines = [
+        `## Workflow: ${spec.name}`,
+        `Type: ${spec.personaType}`,
+        `Description: ${spec.description}`,
+        ``,
+        `### Nodes (${spec.nodes.length})`,
+    ];
+    for (const node of spec.nodes) {
+        const inputs = node.inputs ? Object.keys(node.inputs).join(", ") : "none";
+        const condition = node.runIf
+            ? ` [if ${node.runIf.sourceAction}.${node.runIf.sourceOutput} ${node.runIf.operator} "${node.runIf.value}"]`
+            : "";
+        lines.push(`- ${node.id} (${node.actionType}): ${node.displayName}${condition}`);
+        lines.push(`  Inputs: ${inputs}`);
+    }
+    lines.push(``, `### Output Mappings`);
+    for (const rm of spec.resultMappings) {
+        lines.push(`- ${rm.nodeId}.${rm.output}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Create an LLM prompt for workflow modification.
+ * This should be used by the MCP handler to construct the LLM call.
+ */
+export function createModificationPrompt(currentSpec, userRequest) {
+    return `
+You are modifying an Ema workflow. Your output should be a valid WorkflowSpec JSON.
+
+## Current Workflow
+${summarizeSpec(currentSpec)}
+
+## Current Spec (JSON)
+\`\`\`json
+${JSON.stringify(currentSpec, null, 2)}
+\`\`\`
+
+## Schema Reference
+${WORKFLOW_SCHEMA_FOR_LLM}
+
+## User Request
+${userRequest}
+
+## Instructions
+1. Analyze the user request
+2. Determine what nodes/connections need to change
+3. Output the COMPLETE modified WorkflowSpec as valid JSON
+4. Preserve all unchanged nodes exactly as they are
+5. Only modify what's necessary for the request
+
+## Output
+Return ONLY the modified WorkflowSpec JSON, no explanation needed:
+\`\`\`json
+`;
+}