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

package/resources/templates/auto-builder-rules.md

@@ -1,224 +0,0 @@
-# Auto-Builder Workflow Rules
-
-> These rules are used by the LLM when generating workflow graphs for Ema AI Employees.
-
-## Action-Specific Instructions
-
-### Chat Categorizer (Intent Classifier)
-- Classifies user intent into predefined categories for routing
-- **CRITICAL**: ALWAYS include a `Fallback` category - workflow validation fails without it
-- **MUST** create a handler node for EACH category defined
-- Downstream nodes use `runIf` conditions to check `category` output against `enumValue`
-- **Output**: `category` (enum value) - use `runIf` with `enumValue: "<CategoryName>"` to route
-- **DO NOT** use `category_<Name>` format - use `output: "category"` compared to `enumValue`
-- Example categories: `[Password_Reset, Software_Issue, Account_Access, Fallback]`
-
-#### Graphing Instructions
-- Connect `chat_conversation` to the categorizer's `conversation` input (NOT `user_query`)
-- Each category needs a downstream node with `runIf` comparing `category` to `enumValue`
-- Example runIf structure:
-  ```json
-  {
-    "runIf": {
-      "lhs": {"actionOutput": {"actionName": "chat_categorizer0", "output": "category"}},
-      "operator": 1,
-      "rhs": {"inline": {"enumValue": "Password_Reset"}}
-    }
-  }
-  ```
-
-### Type Compatibility
-- **CHAT_CONVERSATION**: Only compatible with `chat_categorizer.conversation` input
-- **TEXT_WITH_SOURCES**: Used by most other agents (search, respond, call_llm)
-- **SEARCH_RESULT**: Only compatible with `respond_with_sources.search_results` or `named_inputs`
-
-#### Common Type Conversions
-- ✅ `trigger.user_query → search.query` (TEXT_WITH_SOURCES → TEXT_WITH_SOURCES)
-- ❌ `trigger.chat_conversation → search.query` (CHAT_CONVERSATION ≠ TEXT_WITH_SOURCES)
-- ✅ `search.search_results → respond_with_sources.search_results` (compatible)
-- ✅ `search.search_results → call_llm.named_inputs_*` (ANY accepts everything)
-- **Use `conversation_to_search_query`** to convert CHAT_CONVERSATION → TEXT_WITH_SOURCES
-
-### Conversation Summarizer (conversation_to_search_query)
-- Converts conversation history to a condensed search query
-- **When to use**:
-  - Before search nodes when you have `chat_conversation` but need `TEXT_WITH_SOURCES`
-  - For managing long conversation context windows (LLM token limits)
-- **When NOT to use**: When `trigger.user_query` is sufficient for simple queries
-
-### Combine Search Results
-- Combines and weights search results from multiple sources into a unified list
-- Handles both segment-level and chunk-level results while preserving document relationships
-- **IMPORTANT**: Avoid using this agent unless necessary. Use alternatives:
-  - **Rerank Search Results** (`combine_and_rerank_search_results`): Intelligently combines with relevance ranking and max limit
-  - **Respond** (`call_llm`): Allows adding any number of search results via named_inputs with prompt-based ranking control
-
-### Named Inputs (for call_llm, general_hitl)
-- When connecting to `named_inputs`, use the suffix pattern: `named_inputs_<descriptive_name>`
-- Replace spaces with underscores in the name
-- Examples:
-  - `named_inputs_External_Tool_Results` for external action results
-  - `named_inputs_Web_Search_Data` for web search results
-  - `named_inputs_Financial_Analysis` for market research data
-- Each named input will be labeled with the descriptive name in the workflow UI
-- The planner should specify descriptive names like: "Connect to named_inputs as 'External Tool Results'"
-- The grapher will convert this to: `target_input: "named_inputs_External_Tool_Results"`
-- **Accepts ANY type**: Use named_inputs when you need to pass SEARCH_RESULT or other types to call_llm
-
-### Human Collaboration (general_hitl)
-
-#### Planning Instructions
-- Human Collaboration is a special type of categorizer with two fixed categories: "HITL Success" and "HITL Failure" with no fallback categories
-- Use it to pause workflow execution for human input, verification, or decision-making
-- Always plan for both success and failure paths after Human Collaboration
-- **Success criteria**: Define what makes HITL succeed (e.g., "The user approves the output", "The user is happy with the result")
-- **Failure criteria**: Define what makes HITL fail (e.g., "The user wants to restart the workflow", "The user rejects the data")
-- **CRITICAL**: Use HITL for ANY action with external side effects (create ticket, send email, update records)
-
-#### Graphing Instructions
-- Human Collaboration (general_hitl) outputs follow a special pattern:
-  - Success path: `hitl_status_HITL Success`
-  - Failure path: `hitl_status_HITL Failure`
-- Connect these outputs to the `trigger_when` input of subsequent actions
-- **IMPORTANT**: Use exact output names with underscores replaced by spaces in the suffix:
-  - `source_output: "hitl_status_HITL Success"` (with space between HITL and Success)
-  - `source_output: "hitl_status_HITL Failure"` (with space between HITL and Failure)
-- Each Human Collaboration node MUST have at least one outgoing edge
-- **Both paths must lead to valid response nodes and terminate at WORKFLOW_OUTPUT**
-- Example connection:
-  ```json
-  {
-    "source_node_id": "general_hitl0r146c",
-    "source_output": "hitl_status_HITL Success",
-    "target_input": "trigger_when"
-  }
-  ```
-
-### External Tool Caller (external_action_caller)
-- Calls external APIs/tools (ServiceNow, Salesforce, Workday, etc.)
-- **CRITICAL**: Check `chat_conversation` for existing records before creating new ones to avoid duplicates on follow-up messages
-- **Always use HITL before** actions with external side effects (create, update, delete, send)
-- Accepts both `query` (TEXT_WITH_SOURCES) and optional `conversation` (CHAT_CONVERSATION) inputs
-
-### Respond with Sources (respond_with_sources)
-- Generates response grounded in search results with citations
-- **Enable `use_citation_based_filtering`** for trust and verifiability
-- **Implement confidence thresholds** for quality control - abstain when uncertain
-- Accepts `query` (TEXT_WITH_SOURCES) and `search_results` (SEARCH_RESULT)
-
-### WORKFLOW_OUTPUT Mapping
-- **ALL paths must terminate at WORKFLOW_OUTPUT**
-- Every response node (call_llm, respond_with_sources, fixed_response, etc.) needs an edge to WORKFLOW_OUTPUT
-- Missing WORKFLOW_OUTPUT mapping = responses don't reach the user
-- Example: `respond_market.response_with_sources → WORKFLOW_OUTPUT`
-
-### Common Mistakes to Avoid
-1. **Missing Fallback category**: Workflow validation fails, unhandled intents crash
-2. **Missing HITL on sensitive actions**: Unintended actions with external side effects
-3. **Creating duplicate records**: Always check chat_conversation before creating new records
-4. **Type mismatches**: Use conversation_to_search_query when needed
-5. **Vague agent instructions**: Be specific about tone, format, and boundaries
-6. **Not mapping to WORKFLOW_OUTPUT**: Responses won't reach the user
-7. **Not citing sources**: Enable use_citation_based_filtering for trust
-8. **Ignoring confidence scores**: Abstain when uncertain rather than guessing
-
----
-
-## General Instructions
-
-### Validator System Overview
-Your generated workflows will be processed by a validator system that includes:
-- TypeValidator: Strictly enforces type compatibility between connected nodes
-- WorkflowGenerator: Converts valid graphs to workflow definitions  
-- InputProcessor: Handles complex input processing and multibinding logic
-- Categorizer validation: Ensures categorizers have proper outgoing edges
-
-### Workflow Construction Rules
-
-#### 1. Structure Analysis
-- Extract the workflow structure from the natural language description
-- Identify the type of interface: dashboard (document_trigger) or chatbot (chat_trigger)
-
-#### 2. Node Mapping
-- Map each workflow step to appropriate nodes from the available_nodes list
-- You can use multiple instances of the same node if needed
-- Always include at least 3 nodes in total
-- Assign each node a unique ID, with node name as prefix (except trigger nodes)
-
-#### 3. Edge Creation and Type Validation
-- INPUT AND OUTPUT `wellKnownType` MUST MATCH when creating edges - validator will reject mismatches
-- List Level Validation: The source output's `listLevel` MUST be less than or equal to the target input's `listLevel`
-- If source listLevel equals target listLevel: only ONE edge can be created to that input
-- If source listLevel is less than target listLevel: multiple edges can be created from different sources
-
-#### 4. Categorizer Validation Rules
-- **CRITICAL**: If a node has output `category` (such as chat_categorizer, text_categorizer, document_categorizer), it MUST have handler nodes with runIf conditions
-- The runIf format MUST BE: `output: "category"` compared to `enumValue: "<CategoryName>"`
-  - Example: `runIf: { lhs: { actionOutput: { output: "category" } }, operator: 1, rhs: { inline: { enumValue: "Support" } } }`
-- **DO NOT use `category_<Name>` format** - the output is always just `"category"`, compared against the enum value
-- Always add a Fallback category handler
-- **You MUST create a handler with runIf for each category or routing will fail**
-
-#### 5. WELL_KNOWN_TYPE_ANY Rules
-- Inputs with `wellKnownType: "WELL_KNOWN_TYPE_ANY"` accept ANY output type
-- Common in `named_inputs` fields (call_llm, general_hitl actions)
-- Type validation is bypassed for WELL_KNOWN_TYPE_ANY inputs - any source can connect
-- For named_inputs specifically:
-  - Use suffix pattern: `"target_input": "named_inputs_<descriptive_name>"`
-  - Replace spaces with underscores in the name
-  - Example: `"named_inputs_External_Tool_Results"`, `"named_inputs_Web_Search_Data"`
-  - The validator extracts the name and creates namedBinding structures
-
-#### 6. Document Trigger Specific Rules
-- When the initial node is "document_trigger", only use document_metasearch or file_search if additional sources are needed
-- When the initial node is "document_trigger", each output is shown as a column to the user, so make sure to think about what columns user likely wants to see and create nodes and output edges separately
-- The number of columns are equal to the number of outputs
-
-#### 7. Chat Trigger Specific Rules
-- When the initial node is "chat_trigger", the output is a chat conversation returned to the user
-- Every incoming edge to WORKFLOW_OUTPUT node is being shown to the user
-- Make sure to create an edge for each output that the user should see
-
-#### 8. Special Requirements
-- Always start with either document_trigger or chat_trigger node
-- Always end with WORKFLOW_OUTPUT node - all user-visible outputs must connect here
-- Include `is_document` property based on the starting trigger type
-
-#### 9. Critical Validation Rules
-- Follow the exact workflow structure described in the plan
-- Use only nodes from the available_nodes list
-- Ensure perfect input/output type compatibility for all edges
-- Generate valid, parseable output (JSON for grapher, markdown for planner)
-
-### JSON Graph Structure
-The final graph must follow this structure:
-```json
-{
-  "user_query": "description of the workflow",
-  "is_document": true/false,
-  "graph": {
-    "node_id": {
-      "action_name": "action_name_from_available_nodes",
-      "display_name": "Human readable display name",
-      "incoming_edges": [
-        {
-          "source_node_id": "source_node_id",
-          "source_output": "output_name_from_source_node",
-          "target_input": "input_name_for_this_node"
-        }
-      ]
-    },
-    "WORKFLOW_OUTPUT": {
-      "action_name": "WorkflowOutputSink",
-      "display_name": "Workflow Output",
-      "incoming_edges": [
-        {
-          "source_node_id": "node_id",
-          "source_output": "output_name",
-          "target_input": "node_id.output_name"
-        }
-      ]
-    }
-  }
-}
-```

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

@@ -1,119 +0,0 @@
-# {Persona Name}
-
-**Type**: Chat AI
-**Created**: {Date}
-**Version**: 1.0
-
-## Overview
-
-{Brief description of what this Chat 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 **Chat 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 Chat Settings
-
-1. Navigate to "Chat Settings" section
-2. Apply settings from `persona-config.json`:
-
-| Field | Source |
-|-------|--------|
-| Name | `chatbotSdkConfig.name` |
-| Theme Color | `chatbotSdkConfig.theme.primaryColor` |
-| Logo | `chatbotSdkConfig.logo` |
-| Allowed Domains | `chatbotSdkConfig.allowedDomains` |
-
-### Step 3: Configure Knowledge Base
-
-1. Navigate to "Knowledge Base" section
-2. Upload documents from `docs/` folder
-3. Configure tags from `persona-config.json`:
-   - Tag Types: `fileTagging.tagTypes`
-4. Enable chunking: `fileUpload.useChunking`
-
-### Step 4: Configure Feedback
-
-1. Navigate to "Feedback" section
-2. Apply settings:
-   - Question: `feedbackMessage.message.question`
-   - Frequency: `feedbackMessage.feedbackFrequency`
-
-### Step 5: Deploy Widget
-
-1. Get embed code from "Deploy" section
-2. Add to your website:
-
-```html
-<script src="https://widget.ema.co/chat/{persona-id}.js"></script>
-```
-
-### Step 6: Test
-
-1. **Preview Mode**: Use the built-in chat preview
-2. **Test Scenarios**:
-   - Test knowledge base queries
-   - Test each category branch
-   - Test fallback handling
-   - Test source citations
-3. **Edge Cases**:
-   - Test with off-topic queries
-   - Test with multi-turn conversations
-   - Test with complex questions
-
-## Files
-
-| File | Description |
-|------|-------------|
-| `workflow-prompt.md` | Auto Builder prompt with safeguards |
-| `persona-config.json` | Chat AI configuration |
-| `proto-config.json` | Full API-deployable config |
-| `docs/` | Knowledge base documents |
-
-## Testing Checklist
-
-- [ ] Workflow generates without validation errors
-- [ ] Knowledge search returns relevant results
-- [ ] Source citations appear correctly
-- [ ] All category paths work
-- [ ] Fallback provides helpful response
-- [ ] Widget loads on allowed domains
-- [ ] Feedback collection works
-
-## Maintenance
-
-| Change Type | Action |
-|-------------|--------|
-| Workflow logic | Update `workflow-prompt.md`, re-generate |
-| Chat settings | Update `persona-config.json`, apply in UI |
-| Knowledge content | Update docs in `docs/`, re-upload |
-| Allowed domains | Update `chatbotSdkConfig.allowedDomains` |
-
-## Troubleshooting
-
-### Widget doesn't load
-
-- Check `allowedDomains` includes your domain
-- Verify embed code is correct
-- Check browser console for errors
-
-### Poor search results
-
-- Review document chunking settings
-- Add more specific tags
-- Improve document structure
-
-### Missing source citations
-
-- Ensure `disableSources: false`
-- Verify documents have clear headings
-- Check that search is returning results

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

@@ -1,111 +0,0 @@
-{
-  "$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

@@ -1,156 +0,0 @@
-# {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