ema-mcp-toolkit 0.2.0

package/resources/templates/chat-ai/persona-config.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://ema.co/schemas/persona-config-chat.json",
+  "$comment": "Chat AI Persona Configuration - Fill in all {placeholder} values",
+  
+  "personaType": "chat",
+  "projectType": 4,
+  "name": "{Persona Name}",
+  "description": "{Brief description of what this Chat AI does}",
+  
+  "chatbotSdkConfig": {
+    "name": "{Display name shown in chat widget}",
+    "theme": {
+      "primaryColor": "#1f8844",
+      "$comment": "Hex color for chat widget theme"
+    },
+    "logo": "",
+    "$comment_logo": "URL to logo image (optional)",
+    "allowedDomains": ["*"],
+    "$comment_allowedDomains": "Domains where widget can be embedded. Use ['*'] for all, or specific domains",
+    "disableSources": false,
+    "$comment_disableSources": "Set true to hide source citations"
+  },
+  
+  "fileTagging": {
+    "tagTypes": [
+      {
+        "name": "Department",
+        "tags": [
+          { "tagValue": "Department:HR" },
+          { "tagValue": "Department:IT" },
+          { "tagValue": "Department:Finance" }
+        ]
+      },
+      {
+        "name": "DocType",
+        "tags": [
+          { "tagValue": "DocType:Policy" },
+          { "tagValue": "DocType:Procedure" },
+          { "tagValue": "DocType:FAQ" }
+        ]
+      }
+    ],
+    "$comment": "Define tag categories and values for knowledge base filtering"
+  },
+  
+  "fileUpload": {
+    "localFiles": [],
+    "mergeFiles": [],
+    "tags": ["{default-tag}"],
+    "$comment_tags": "Default tags applied to all uploads",
+    "transforms": [],
+    "useChunking": true,
+    "$comment_useChunking": "Enable for better search on long documents",
+    "fileTagMappings": [],
+    "acceptedMimeTypes": [
+      "application/pdf",
+      "text/plain",
+      "text/markdown",
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "text/csv"
+    ]
+  },
+  
+  "feedbackMessage": {
+    "message": {
+      "question": "Was this answer helpful?",
+      "positiveLabel": "Yes, helpful",
+      "negativeLabel": "No, not helpful"
+    },
+    "feedbackFrequency": 1,
+    "$comment_feedbackFrequency": "1 = every response, 3 = every 3rd response"
+  },
+  
+  "dataProtection": {
+    "protectedClasses": [
+      "ssn",
+      "credit_card"
+    ],
+    "$comment": "PII classes to redact from responses"
+  },
+  
+  "fusionModel": {
+    "allModels": true,
+    "selectedModels": []
+  },
+  
+  "knowledgeBaseSettings": {
+    "$comment": "These settings guide how the knowledge base should be configured",
+    "sources": [
+      {
+        "name": "{Source 1 Name}",
+        "type": "documents",
+        "folder": "docs/{folder1}",
+        "tags": ["{tag1}", "{tag2}"],
+        "priority": "primary"
+      },
+      {
+        "name": "{Source 2 Name}",
+        "type": "documents",
+        "folder": "docs/{folder2}",
+        "tags": ["{tag3}"],
+        "priority": "secondary"
+      }
+    ],
+    "searchSettings": {
+      "useSemanticSearch": true,
+      "useKeywordSearch": true,
+      "maxResults": 5
+    }
+  }
+}

package/resources/templates/dashboard-ai/README.md

@@ -0,0 +1,156 @@
+# {Persona Name}
+
+**Type**: Dashboard AI
+**Created**: {Date}
+**Version**: 1.0
+
+## Overview
+
+{Brief description of what this Dashboard AI Employee does}
+
+## Deployment Steps
+
+### Step 1: Create Workflow in Auto Builder
+
+1. Go to [Ema Auto Builder](https://builder.ema.co/)
+2. Create new AI Employee → Select **Dashboard AI**
+3. Copy contents of `workflow-prompt.md` into the prompt field
+4. Click "Generate Workflow"
+5. Review generated nodes and verify:
+   - Document trigger configured correctly
+   - Entity extraction columns defined
+   - Rule validation rules specified
+   - All processing paths complete
+
+### Step 2: Configure Input Schema
+
+1. Navigate to "Input Configuration" section
+2. Define input fields from `persona-config.json`:
+
+| Field | Type | Required |
+|-------|------|----------|
+| {field1} | {type} | {yes/no} |
+| {field2} | {type} | {yes/no} |
+
+### Step 3: Configure Processing Settings
+
+1. Navigate to "Processing" section
+2. Apply settings:
+   - Batch Size: `dashboardSettings.batchSettings.batchSize`
+   - Timeout: `dashboardSettings.batchSettings.timeout`
+   - Parallel: `dashboardSettings.batchSettings.parallelExecution`
+
+### Step 4: Upload Reference Documents (if applicable)
+
+1. Navigate to "Knowledge Base" section
+2. Upload documents from `docs/` folder
+3. Configure entity extraction mappings
+
+### Step 5: Configure Approvals (if applicable)
+
+1. Navigate to "Approval Routing" section
+2. Define approval rules:
+   - Thresholds for auto-approval
+   - Routing rules for human review
+   - Escalation paths
+
+### Step 6: Test
+
+1. **Single Item Test**: Process one document
+2. **Batch Test**: Process small batch (5-10 items)
+3. **Edge Cases**:
+   - Missing required fields
+   - Invalid data formats
+   - Processing failures
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `workflow-prompt.md` | Auto Builder prompt with safeguards |
+| `persona-config.json` | Dashboard AI configuration |
+| `proto-config.json` | Full API-deployable config |
+| `docs/` | Reference documents |
+
+## Testing Checklist
+
+- [ ] Workflow generates without validation errors
+- [ ] Document upload works
+- [ ] Entity extraction accurate
+- [ ] Rule validation correct
+- [ ] Approval routing works
+- [ ] Batch processing completes
+- [ ] Error handling works
+
+## Input Schema
+
+```json
+{
+  "fields": [
+    {
+      "name": "{field1}",
+      "type": "{string|number|date|file}",
+      "required": true,
+      "description": "{Field description}"
+    }
+  ]
+}
+```
+
+## Processing Flow
+
+```
+Input Document
+     │
+     ▼
+┌─────────────┐
+│ Parse/OCR   │
+└─────────────┘
+     │
+     ▼
+┌─────────────┐
+│ Extract     │──→ {Field 1}
+│ Entities    │──→ {Field 2}
+└─────────────┘──→ {Field N}
+     │
+     ▼
+┌─────────────┐
+│ Validate    │──→ Errors?
+│ Rules       │
+└─────────────┘
+     │
+     ▼
+┌─────────────┐
+│ Route for   │──→ Auto-approve
+│ Approval    │──→ Human review
+└─────────────┘──→ Reject
+```
+
+## Maintenance
+
+| Change Type | Action |
+|-------------|--------|
+| Workflow logic | Update `workflow-prompt.md`, re-generate |
+| Processing settings | Update `persona-config.json`, apply in UI |
+| Extraction rules | Update entity extraction columns |
+| Validation rules | Update rule validation configuration |
+
+## Troubleshooting
+
+### Processing fails
+
+- Check document format is supported
+- Verify required fields are present
+- Review extraction column mappings
+
+### Entity extraction inaccurate
+
+- Add more training examples
+- Refine extraction column definitions
+- Check document quality
+
+### Batch processing slow
+
+- Reduce batch size
+- Increase timeout
+- Enable parallel execution

package/resources/templates/dashboard-ai/persona-config.json

@@ -0,0 +1,180 @@
+{
+  "$schema": "https://ema.co/schemas/persona-config-dashboard.json",
+  "$comment": "Dashboard AI Persona Configuration - Fill in all {placeholder} values",
+  
+  "personaType": "dashboard",
+  "projectType": 2,
+  "name": "{Persona Name}",
+  "description": "{Brief description of what this Dashboard AI does}",
+  
+  "dashboardSettings": {
+    "name": "{Display name}",
+    "description": "{What this dashboard processes}",
+    
+    "inputSchema": {
+      "fields": [
+        {
+          "name": "{field1}",
+          "type": "file",
+          "required": true,
+          "description": "{Primary document to process}",
+          "acceptedTypes": ["application/pdf", "image/*"]
+        },
+        {
+          "name": "{field2}",
+          "type": "string",
+          "required": false,
+          "description": "{Optional text field}"
+        },
+        {
+          "name": "{field3}",
+          "type": "select",
+          "required": true,
+          "options": ["{option1}", "{option2}", "{option3}"],
+          "description": "{Category selection}"
+        }
+      ]
+    },
+    
+    "batchSettings": {
+      "batchSize": 50,
+      "$comment_batchSize": "Number of items per batch (1-100)",
+      "timeout": 60,
+      "$comment_timeout": "Seconds per item before timeout",
+      "parallelExecution": true,
+      "$comment_parallelExecution": "Process items in parallel"
+    },
+    
+    "outputSchema": {
+      "fields": [
+        {
+          "name": "status",
+          "type": "enum",
+          "values": ["approved", "pending_review", "rejected"]
+        },
+        {
+          "name": "extracted_data",
+          "type": "object",
+          "description": "Extracted entity values"
+        },
+        {
+          "name": "validation_errors",
+          "type": "array",
+          "description": "List of validation failures"
+        },
+        {
+          "name": "confidence_score",
+          "type": "number",
+          "description": "0-1 confidence in extraction"
+        }
+      ]
+    }
+  },
+  
+  "entityExtraction": {
+    "columns": [
+      {
+        "name": "{Entity 1}",
+        "type": "string",
+        "description": "{What to extract}",
+        "examples": ["{example1}", "{example2}"]
+      },
+      {
+        "name": "{Entity 2}",
+        "type": "number",
+        "description": "{Numeric value to extract}",
+        "examples": ["{example1}", "{example2}"]
+      },
+      {
+        "name": "{Entity 3}",
+        "type": "date",
+        "description": "{Date to extract}",
+        "format": "YYYY-MM-DD"
+      }
+    ],
+    "$comment": "Define columns for entity_extraction_with_documents action"
+  },
+  
+  "ruleValidation": {
+    "rules": [
+      {
+        "name": "{Rule 1}",
+        "description": "{What this rule checks}",
+        "condition": "{Entity 1} is not empty",
+        "severity": "error"
+      },
+      {
+        "name": "{Rule 2}",
+        "description": "{What this rule checks}",
+        "condition": "{Entity 2} > 0",
+        "severity": "warning"
+      }
+    ],
+    "$comment": "Define rules for rule_validation_with_documents action"
+  },
+  
+  "approvalRouting": {
+    "rules": [
+      {
+        "name": "Auto-approve",
+        "condition": "confidence_score >= 0.95 AND validation_errors.length == 0",
+        "action": "auto_approve"
+      },
+      {
+        "name": "Manager Review",
+        "condition": "{amount} > 10000",
+        "action": "route_to_manager",
+        "assignee": "{manager_email}"
+      },
+      {
+        "name": "Reject",
+        "condition": "validation_errors contains 'critical'",
+        "action": "reject"
+      }
+    ],
+    "sla": {
+      "standard": "24h",
+      "urgent": "4h",
+      "reminderAt": "50%",
+      "escalateAt": "100%"
+    }
+  },
+  
+  "fileUpload": {
+    "localFiles": [],
+    "tags": ["{default-tag}"],
+    "useChunking": true,
+    "acceptedMimeTypes": [
+      "application/pdf",
+      "image/png",
+      "image/jpeg",
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    ]
+  },
+  
+  "dataProtection": {
+    "protectedClasses": [
+      "ssn",
+      "credit_card",
+      "account_number"
+    ]
+  },
+  
+  "fusionModel": {
+    "allModels": true,
+    "selectedModels": []
+  },
+  
+  "notifications": {
+    "onSuccess": {
+      "enabled": true,
+      "recipients": ["{email}"],
+      "template": "Processing complete: {count} items processed"
+    },
+    "onFailure": {
+      "enabled": true,
+      "recipients": ["{email}"],
+      "template": "Processing failed: {error}"
+    }
+  }
+}

package/resources/templates/voice-ai/README.md

@@ -0,0 +1,123 @@
+# {Persona Name}
+
+**Type**: Voice AI
+**Created**: {Date}
+**Version**: 1.0
+
+## Overview
+
+{Brief description of what this Voice AI Employee does}
+
+## Deployment Steps
+
+### Step 1: Create Workflow in Auto Builder
+
+1. Go to [Ema Auto Builder](https://builder.ema.co/)
+2. Create new AI Employee → Select **Voice AI**
+3. Copy contents of `workflow-prompt.md` into the prompt field
+4. Click "Generate Workflow"
+5. Review generated nodes and verify:
+   - All categorizers have edges for every category
+   - Search nodes connect to respond nodes correctly
+   - Fallback paths are present
+
+### Step 2: Configure Conversational Behavior
+
+1. Navigate to "Conversational Behavior" section
+2. Apply settings from `persona-config.json`:
+
+| Field | Source |
+|-------|--------|
+| Welcome Message | `conversationSettings.welcomeMessage` |
+| Identity & Purpose | `conversationSettings.identityAndPurpose` |
+| Take Action Instructions | `conversationSettings.takeActionInstructions` |
+| Hangup Instructions | `conversationSettings.hangupInstructions` |
+| Transfer Call Instructions | `conversationSettings.transferCallInstructions` |
+| Speech Characteristics | `conversationSettings.speechCharacteristics` |
+| System Prompt | `conversationSettings.systemPrompt` |
+| Wait Message | `conversationSettings.waitMessage` |
+
+### Step 3: Configure Voice Settings
+
+1. Navigate to "Voice Settings" section
+2. Apply settings:
+   - Language: From `voiceSettings.languageHints`
+   - Voice Model: From `voiceSettings.voiceModel`
+
+### Step 4: Configure VAD & Data Storage
+
+1. **VAD Settings** (Voice Activity Detection):
+   - Turn Timeout: `vadSettings.turnTimeout` seconds
+   - Silence End Call: `vadSettings.silenceEndCallTimeout` seconds
+   - Max Duration: `vadSettings.maxConversationDuration` seconds
+
+2. **Data Storage**:
+   - Store Audio: `dataStorageSettings.storeAudioRecording`
+   - Store Transcripts: `dataStorageSettings.storeTranscripts`
+
+### Step 5: Upload Knowledge Base (if applicable)
+
+1. Navigate to "Knowledge Base" section
+2. Upload documents from `docs/` folder
+3. Apply tags as specified in `docs/_metadata.json`
+
+### Step 6: Test
+
+1. **Simulator Test**: Use the built-in call simulator
+2. **Test Calls**:
+   - Test happy path (main use case)
+   - Test each category branch
+   - Test fallback handling
+   - Test verification flows (if applicable)
+3. **Edge Cases**:
+   - Test with unexpected inputs
+   - Test silence handling
+   - Test interruption handling
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `workflow-prompt.md` | Auto Builder prompt with safeguards |
+| `persona-config.json` | Voice AI configuration |
+| `proto-config.json` | Full API-deployable config |
+| `docs/` | Knowledge base documents |
+
+## Testing Checklist
+
+- [ ] Workflow generates without validation errors
+- [ ] All category paths work correctly
+- [ ] Fallback provides helpful response
+- [ ] Voice sounds natural and appropriate
+- [ ] Actions/tools execute correctly
+- [ ] Handoff to human works (if applicable)
+- [ ] Call ends appropriately
+
+## Maintenance
+
+| Change Type | Action |
+|-------------|--------|
+| Workflow logic | Update `workflow-prompt.md`, re-generate |
+| Persona behavior | Update `persona-config.json`, apply in UI |
+| Knowledge content | Update docs in `docs/`, re-upload |
+| Voice settings | Update `persona-config.json`, apply in UI |
+
+## Troubleshooting
+
+### "Validation failed" in Auto Builder
+
+- Check that all categorizers have Fallback category
+- Verify edge format: `category_<Name>` not `category::<Name>`
+- Ensure all nodes have required inputs
+
+### Voice sounds unnatural
+
+- Review `speechCharacteristics` for TTS rules
+- Add pronunciation guides for technical terms
+- Adjust pauses and pacing instructions
+
+### Actions not triggering
+
+- Check `takeActionInstructions` uses correct `</Case N>` format
+- Verify tool names match exactly
+- Review `systemPrompt` for tool calling rules

package/resources/templates/voice-ai/persona-config.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://ema.co/schemas/persona-config-voice.json",
+  "$comment": "Voice AI Persona Configuration - Fill in all {placeholder} values",
+  
+  "personaType": "voice",
+  "projectType": 5,
+  "name": "{Persona Name}",
+  "description": "{Brief description of what this Voice AI does}",
+  
+  "conversationSettings": {
+    "name": "{AI Name - e.g., 'Sofia', 'Alex', 'Service Agent'}",
+    
+    "welcomeMessage": "{Opening greeting when call connects}\n\nExample:\nHello, thank you for calling {Company}. This is {AI Name}. How can I help you today?",
+    
+    "identityAndPurpose": "You are {AI Name}, a Voice AI assistant for {Company}.\n\nPrimary responsibility: {Main purpose}\n\nYour responsibilities:\n1. {Responsibility 1}\n2. {Responsibility 2}\n3. {Responsibility 3}\n\nRules:\n- {Rule 1}\n- {Rule 2}",
+    
+    "takeActionInstructions": "</Case 1>\n{Action 1 Name}\n\nTrigger When:\n{Condition that triggers this action}\n\nIntent for tool call: \"{Tool Intent Name}\"\n\nRequired parameters:\n{ \"{param1}\": \"\", \"{param2}\": \"\" }\n</Case 1>\n\n</Case 2>\n{Action 2 Name}\n\nTrigger When:\n{Condition that triggers this action}\n\nIntent for tool call: \"{Tool Intent Name}\"\n\nRequired parameters:\n{ \"{param1}\": \"\" }\n</Case 2>",
+    
+    "hangupInstructions": "End the call when:\n- The caller explicitly says goodbye or asks to hang up\n- The caller confirms they have no more questions\n- {Additional hangup conditions}\n\nBefore ending:\n- Confirm all issues are resolved\n- Offer any follow-up information\n- Thank the caller",
+    
+    "transferCallInstructions": "Transfer the call when:\n- The caller explicitly requests a human agent\n- {Condition requiring human}\n- {Complex scenario}\n\nBefore transferring:\n- Inform the caller you're transferring them\n- Provide brief context to the human agent\n- {Additional transfer instructions}",
+    
+    "speechCharacteristics": "**Conversational Style:**\n- Keep responses brief (2-3 sentences per turn)\n- Use warm, professional tone\n- Speak clearly at moderate pace\n\n**Natural Speech:**\n- Use brief pauses between sentences\n- Acknowledge with 'I understand', 'Of course', 'Certainly'\n- Avoid robotic language\n\n**TTS Pronunciation Rules:**\n- Spell out IDs: 'A-B-C-1-2-3'\n- Pause between numbers: 'Your code is... 1... 2... 3... 4'\n- {Domain-specific pronunciation rules}",
+    
+    "systemPrompt": "Tool Calling Instructions:\n\n1. Always collect required parameters before calling tools\n2. Confirm parameter values with the caller\n3. Handle tool errors gracefully\n4. {Additional tool calling rules}\n\nParameter Collection:\n- {Param 1}: {How to collect}\n- {Param 2}: {How to collect}",
+    
+    "formFillingInstructions": "{Instructions for collecting form data, if applicable}\n\nExample:\nWhen collecting booking information:\n1. Ask for name first\n2. Then ask for date preference\n3. Confirm all details before proceeding",
+    
+    "waitMessage": "One moment while I look that up for you..."
+  },
+  
+  "voiceSettings": {
+    "languageHints": ["en-US"],
+    "voiceModel": "default",
+    "$comment_voiceModel": "Options: default, professional-male, professional-female, casual"
+  },
+  
+  "vadSettings": {
+    "turnTimeout": 3,
+    "$comment_turnTimeout": "Seconds to wait for caller to finish speaking",
+    "silenceEndCallTimeout": 30,
+    "$comment_silenceEndCallTimeout": "Seconds of silence before ending call",
+    "maxConversationDuration": 600,
+    "$comment_maxConversationDuration": "Maximum call length in seconds (600 = 10 minutes)"
+  },
+  
+  "dataStorageSettings": {
+    "storeAudioRecording": true,
+    "storeTranscripts": true,
+    "storeAgentTranscript": true
+  },
+  
+  "callSettings": {
+    "enableCallForwarding": false,
+    "callForwardingNumber": "",
+    "enableSpamCallPrevention": true,
+    "enableDisconnectCall": false
+  },
+  
+  "dataProtection": {
+    "protectedClasses": [
+      "ssn",
+      "credit_card",
+      "phone_number"
+    ],
+    "$comment_protectedClasses": "PII classes to redact. Options: ssn, credit_card, phone_number, email, address, dob, account_number"
+  },
+  
+  "fusionModel": {
+    "allModels": true,
+    "selectedModels": [],
+    "$comment": "Leave allModels: true for best results, or specify models: ['gpt-4', 'claude-3']"
+  }
+}