@ema.co/mcp-toolkit 2026.1.24 → 2026.1.26-3

package/docs/llm-native-workflow-design.md

@@ -1,252 +0,0 @@
-# LLM-Native Workflow Transformation Design
-
-## The Problem
-
-Current `workflow(mode="extend")` uses keyword matching:
-```typescript
-// handlers-consolidated.ts - FRAGILE APPROACH
-if (lowerInput.includes("consolidat") || lowerInput.includes("merge")) {
-  intent = "consolidate multiple nodes into one";
-  // ... pattern matching logic
-}
-```
-
-This is backwards - we're **sidelining the LLM** and using brittle string matching.
-
-## The Solution
-
-**Let the LLM BE the transformation engine.**
-
-Workflows are just JSON. LLMs excel at:
-1. Understanding natural language intent
-2. Transforming structured data
-3. Following schemas and rules
-
-### New Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        USER REQUEST                             │
-│     "Fix all email nodes to use entity_extraction output"       │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    DECOMPILE WORKFLOW                           │
-│              workflow_def JSON → WorkflowSpec                   │
-│                                                                 │
-│  • Typed nodes, inputs, outputs                                 │
-│  • Human-readable structure                                     │
-│  • Easy for LLM to reason about                                 │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    LLM TRANSFORMATION                           │
-│                                                                 │
-│  Context provided:                                              │
-│  • Current WorkflowSpec                                         │
-│  • WORKFLOW_SCHEMA_FOR_LLM (full schema documentation)          │
-│  • User request                                                 │
-│                                                                 │
-│  LLM outputs:                                                   │
-│  • Modified WorkflowSpec JSON                                   │
-│                                                                 │
-│  This is WHERE THE MAGIC HAPPENS - LLM understands intent       │
-│  and transforms the spec accordingly.                           │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    COMPILE & VALIDATE                           │
-│              WorkflowSpec → workflow_def JSON                   │
-│                                                                 │
-│  • compileWorkflow() generates deployment-ready JSON            │
-│  • detectWorkflowIssues() validates result                      │
-│  • Type system catches errors                                   │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                         DEPLOY                                  │
-│               client.updateAiEmployee()                         │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Key Components
-
-#### 1. WorkflowSpec (Typed Schema)
-```typescript
-interface WorkflowSpec {
-  name: string;
-  description: string;
-  personaType: "voice" | "chat" | "dashboard";
-  nodes: Node[];
-  resultMappings: ResultMapping[];
-}
-
-interface Node {
-  id: string;
-  actionType: ActionType;  // "search" | "call_llm" | "send_email_agent" | ...
-  displayName: string;
-  inputs?: Record<string, InputBinding>;
-  runIf?: RunIfCondition;
-  categories?: Category[];
-}
-
-interface InputBinding {
-  type: "action_output" | "inline_string" | ...;
-  actionName?: string;  // Source node
-  output?: string;      // Source output
-  value?: string;       // Inline value
-}
-```
-
-#### 2. WORKFLOW_SCHEMA_FOR_LLM
-A comprehensive schema document (~300 lines) that includes:
-- All type definitions
-- Available action types and their inputs/outputs
-- Common patterns (RAG, Intent Routing, Email with HITL)
-- Transformation rules
-
-This is injected into the LLM context so it knows exactly how to modify workflows.
-
-#### 3. decompileWorkflow()
-```typescript
-function decompileWorkflow(
-  workflowDef: Record<string, unknown>,
-  personaType: PersonaType
-): WorkflowSpec
-```
-Converts raw JSON to typed spec for LLM to work with.
-
-#### 4. transformWorkflow()
-```typescript
-function transformWorkflow(
-  originalDef: Record<string, unknown>,
-  modifiedSpec: WorkflowSpec
-): TransformResult
-```
-Takes the LLM's modified spec and compiles it back to deployment JSON.
-
-### Example: Fixing Email Wiring
-
-**Before (Current Approach)**
-```
-User: "Wire entity_extraction to email"
-       ↓
-analyzeModificationRequest() ← Keyword matching
-       ↓
-"rewire connections" detected
-       ↓
-applyWorkflowModifications() ← Can't handle complex wiring
-       ↓
-FAILURE ❌
-```
-
-**After (LLM-Native Approach)**
-```
-User: "Wire entity_extraction to email"
-       ↓
-decompileWorkflow() → WorkflowSpec
-       ↓
-LLM receives spec + schema + request
-       ↓
-LLM outputs modified spec:
-{
-  nodes: [
-    ...
-    {
-      id: "send_email_1",
-      inputs: {
-        to_email: {
-          type: "action_output",
-          actionName: "entity_extraction_1",  // ← Changed
-          output: "extracted_entities"         // ← Changed
-        }
-      }
-    }
-  ]
-}
-       ↓
-transformWorkflow() → Compiled JSON
-       ↓
-SUCCESS ✅
-```
-
-### Why This Works
-
-1. **Language models understand intent** - No keyword matching needed
-2. **Structured data transformation** - JSON in, JSON out
-3. **Schema as documentation** - LLM knows the rules
-4. **Type safety** - Compiler catches errors
-5. **Composable** - Each piece does one thing well
-
-### Integration Path
-
-1. **Short term**: Use `createModificationPrompt()` to generate LLM prompts
-2. **Medium term**: Integrate with MCP handler for `workflow(mode="extend")`
-3. **Long term**: Replace `analyzeModificationRequest` entirely
-
-### Files
-
-- `src/sdk/workflow-transformer.ts` - Decompiler, transformer, schema
-- `src/sdk/workflow-generator.ts` - Compiler (existing)
-- `test/workflow-transformer.test.ts` - Tests proving the approach
-
-### The Cursor/MCP Integration
-
-When a user asks to modify a workflow, the MCP handler should:
-
-```typescript
-async function handleExtend(args, client) {
-  // 1. Get current workflow
-  const persona = await client.getPersonaById(args.persona_id);
-  const workflowDef = persona.workflow_def;
-  
-  // 2. Decompile to spec
-  const currentSpec = decompileWorkflow(workflowDef, persona.type);
-  
-  // 3. Create prompt for LLM
-  const prompt = createModificationPrompt(currentSpec, args.input);
-  
-  // 4. Return prompt + context for LLM to process
-  // The LLM (Cursor) will see this and output the modified spec
-  return {
-    mode: "extend",
-    prompt,
-    current_spec: currentSpec,
-    schema: WORKFLOW_SCHEMA_FOR_LLM,
-    instruction: "Modify the spec and call workflow(mode='apply', spec=<modified_spec>)"
-  };
-}
-
-async function handleApply(args, client) {
-  // 5. LLM calls back with modified spec
-  const modifiedSpec = args.spec;
-  
-  // 6. Transform and deploy
-  const result = transformWorkflow(originalDef, modifiedSpec);
-  
-  if (result.success && !args.preview) {
-    await client.updateAiEmployee({
-      persona_id: args.persona_id,
-      workflow: result.workflow_def
-    });
-  }
-  
-  return result;
-}
-```
-
-### Success Criteria
-
-With this approach, the following should have **near 100% success rate**:
-- Rewiring connections between nodes
-- Adding/removing nodes
-- Adding conditional execution (runIf)
-- Adding HITL approval flows
-- Modifying categories
-- Consolidating multiple nodes
-
-All because the LLM (not keyword matching) does the thinking.