{ "MASTER_INTENT_ROUTING_METADATA": { "version": "2.0.0", "description": "Embedding-based intent routing configuration for WhatsApp Business Flow Master Agent. Vector similarity is the PRIMARY routing engine. Keyword rules are FALLBACK only.", "primary_engine": "VECTOR_EMBEDDING_SIMILARITY", "fallback_engine": "KEYWORD_RULE_MATCH", "embedding_model": "Universal Sentence Encoder (512-dim)", "intent_confidence_threshold": 0.62, "keyword_fallback_threshold": 0.50, "active_context_boost": 0.12, "sticky_agent_bias": 0.10, "priority_order": [ "1_intent_embedding_match", "2_multi_intent_decomposition", "3_active_child_context", "4_expected_next_step_context", "5_keyword_fallback", "6_minimal_clarification" ], "child_agents": [ { "alias": "Onboarding Helper", "id_ref": "onboarding", "routing_priority": 95 }, { "alias": "Template Helper", "id_ref": "template", "routing_priority": 90 }, { "alias": "Campaign Helper", "id_ref": "campaign", "routing_priority": 88 }, { "alias": "Chatbot Helper", "id_ref": "chatbot", "routing_priority": 85 } ] }, "INTENT_TAXONOMY": { "description": "Complete flat list of all recognized master-level routing intents with grouping.", "total_intents": 32, "groups": { "ONBOARDING": [ "onboarding_start", "onboarding_continue", "onboarding_eligibility", "onboarding_readiness", "onboarding_manual_setup", "onboarding_auto_setup", "onboarding_verification_status" ], "TEMPLATE": [ "template_start", "template_continue", "template_review", "template_improvement", "template_interactive_help", "template_button_help" ], "CAMPAIGN": [ "campaign_start", "campaign_continue", "campaign_status", "campaign_analytics", "campaign_edit", "campaign_troubleshooting", "campaign_schedule_help" ], "CHATBOT": [ "chatbot_start", "chatbot_continue", "chatbot_publish", "chatbot_trigger_setup", "chatbot_edit", "chatbot_troubleshooting", "chatbot_response_type_help" ], "MASTER_CROSS_FLOW": [ "multi_intent_request", "switch_agent_request", "return_to_previous_agent", "dependency_resolution_request", "ambiguous_business_help" ] } }, "VECTOR_EMBEDDING_ROUTING_RULES": { "description": "How embedding-based routing works end-to-end in the Master Agent.", "pipeline": [ { "step": 1, "name": "Embed user message", "action": "Compute 512-dim USE embedding for incoming user text" }, { "step": 2, "name": "Score against intent clusters", "action": "Compute cosine similarity between user embedding and each intent's semantic_centroid (average of semantic_cluster_examples embeddings)", "formula": "score(intent_i) = cosine_similarity(user_vec, centroid_i)" }, { "step": 3, "name": "Apply context boosts", "action": "Add active_context_boost (0.12) to intents belonging to the active child agent. Add sticky_agent_bias (0.10) if active_child_agent matches the intent's child_agent_target.", "formula": "final_score(i) = raw_score(i) + (active_context_boost if active_child matches) + (sticky_bias if sticky applies)" }, { "step": 4, "name": "Select top-1 intent", "action": "Pick intent with highest final_score. If final_score >= intent_confidence_threshold (0.62), route to that intent's child_agent_target.", "tie_break": "If top-2 scores are within 0.05 of each other, check active child context — active child's intent wins the tie." }, { "step": 5, "name": "Multi-intent check", "action": "If top-2 intents have scores >= 0.58 AND belong to DIFFERENT child agents, treat as multi-intent request. Primary = top-1 child, secondary queued.", "threshold_gap": "Multi-intent triggers only if gap between top-1 and top-2 is <= 0.06" }, { "step": 6, "name": "Keyword fallback", "action": "If top-1 embedding score < intent_confidence_threshold (0.62), fall through to keyword rule evaluation (existing MasterRouteRules in DB)." }, { "step": 7, "name": "Clarification fallback", "action": "If both embedding and keyword scores are below threshold, trigger minimal clarification. Never default-route." } ], "centroid_update_policy": "Recompute intent centroids when new positive_examples are added via admin. Cache centroids in Redis with 6h TTL.", "embedding_source": "routingEngine.service.js — _computeEmbeddingScore(userText, intentExamples)" }, "CHILD_AGENT_INTENT_RULES": { "onboarding": [ { "intent_rule_id": "OR-001", "child_agent_target": "Onboarding Helper", "intent_name": "onboarding_start", "intent_description": "User wants to begin WhatsApp Business API account registration from scratch. No prior session context.", "routing_priority_weight": 95, "embedding_intent_label": "begin whatsapp business api account registration", "semantic_cluster_examples": [ "I want to set up WhatsApp Business API", "How do I connect WhatsApp for my business", "I need to get started with WABA", "Help me register for WhatsApp API", "I want to integrate WhatsApp into my platform", "How can I use WhatsApp for sending business messages", "I need a WhatsApp Business account for my company", "Get me started with WhatsApp API access", "Can you help me activate WhatsApp for my business", "Start the WhatsApp setup process" ], "positive_examples": [ "I want to connect WhatsApp to my business", "How do I get started with WhatsApp API", "I need WhatsApp Business account setup", "Help me begin the WABA process", "How do I apply for WhatsApp Business API" ], "confusing_non_matching_examples": [ "I already started setup — continue please (→ onboarding_continue)", "Am I eligible for WhatsApp API? (→ onboarding_eligibility)", "Is my business verified? (→ onboarding_verification_status)" ], "similarity_guidance": "Phrases about 'getting started', 'register', 'apply', 'activate', 'connect' from scratch → strong match. Phrases about resuming or checking status → route to onboarding_continue or onboarding_verification_status.", "disambiguation_notes": "Distinguish from onboarding_continue by absence of past-tense indicators ('was setting up', 'already started', 'where I left off').", "when_to_use": "User initiates WABA setup with no prior session or explicit fresh-start signal.", "when_not_to_use": "Active onboarding session exists and user is mid-flow (use onboarding_continue).", "fallback_behavior": "If confidence 0.50–0.62: apply keyword fallback for 'waba', 'whatsapp business api', 'register', 'embedded signup'.", "dependency_check": "None — this is the root dependency for all other flows." }, { "intent_rule_id": "OR-002", "child_agent_target": "Onboarding Helper", "intent_name": "onboarding_continue", "intent_description": "User has an existing onboarding session and wants to resume from where they left off.", "routing_priority_weight": 94, "embedding_intent_label": "resume existing whatsapp business setup in progress", "semantic_cluster_examples": [ "I was setting up my WhatsApp account earlier", "Continue from where I left off", "I already started the onboarding process", "Let me resume the setup", "I did the first few steps, what is next", "Where was I in the registration", "I need to complete my WhatsApp setup", "Pick up from where we stopped", "I had started the business account registration", "I filled the form, what should I do next" ], "positive_examples": [ "Continue my WhatsApp setup", "I started the process earlier, let me resume", "I already began onboarding, what is the next step", "Where did I stop in the WABA setup", "I need to finish setting up my account" ], "confusing_non_matching_examples": [ "I want to start fresh (→ onboarding_start)", "Has my account been verified? (→ onboarding_verification_status)", "Am I ready to begin? (→ onboarding_readiness)" ], "similarity_guidance": "Past-tense or 'resume' framing → strong match. 'Continue' alone with no session → clarify first.", "disambiguation_notes": "Key signals: 'already started', 'was doing', 'left off', 'resume', 'next step'. Compare with onboarding_start (no prior context) and onboarding_readiness (pre-start checklist).", "when_to_use": "Active onboarding session exists OR user explicitly signals prior progress.", "when_not_to_use": "No prior session and user has never started (use onboarding_start).", "fallback_behavior": "If confidence 0.50–0.62: check session DB for existing onboarding session. If found, route with sticky agent bias.", "dependency_check": "None additional." }, { "intent_rule_id": "OR-003", "child_agent_target": "Onboarding Helper", "intent_name": "onboarding_eligibility", "intent_description": "User wants to know if their business or phone number qualifies for WhatsApp Business API.", "routing_priority_weight": 93, "embedding_intent_label": "check if business or number qualifies for whatsapp api", "semantic_cluster_examples": [ "Am I eligible for WhatsApp Business API", "Can my business use WABA", "Do I qualify for WhatsApp API", "What are the requirements to get WhatsApp API", "Can I use my current phone number for this", "Is my business type allowed on WhatsApp API", "Will my account get approved", "What kind of businesses can use WhatsApp API", "Does my company meet the criteria", "Is WhatsApp API available for small businesses" ], "positive_examples": [ "Can I use my existing number for WhatsApp API", "Is my business eligible", "How do I know if I qualify", "What do I need to be approved", "Am I allowed to use WABA" ], "confusing_non_matching_examples": [ "Am I ready to start? (→ onboarding_readiness — readiness = prerequisites done, eligibility = do I qualify at all)", "Is my account verified? (→ onboarding_verification_status)", "I want to begin setup (→ onboarding_start)" ], "similarity_guidance": "'Eligible', 'qualify', 'allowed', 'requirements', 'can I use' → strong match. 'Ready' alone is ambiguous — check for 'checklist' context for readiness vs eligibility.", "disambiguation_notes": "Eligibility = 'can my business use this at all'. Readiness = 'have I done all steps to begin'. These are semantically close — use active context to break tie.", "when_to_use": "User asks about qualification, approval criteria, or business type restrictions.", "when_not_to_use": "User already in onboarding and asks mid-flow — use ask_eligibility_mid_flow (context-gated intent in child) instead.", "fallback_behavior": "Keyword fallback: 'eligible', 'qualify', 'requirements', 'allowed', 'criteria'.", "dependency_check": "None — eligibility question can occur before onboarding starts." }, { "intent_rule_id": "OR-004", "child_agent_target": "Onboarding Helper", "intent_name": "onboarding_readiness", "intent_description": "User wants to verify that all prerequisites are in place before starting the onboarding process.", "routing_priority_weight": 92, "embedding_intent_label": "verify prerequisites and readiness checklist before starting whatsapp setup", "semantic_cluster_examples": [ "Am I ready to start the setup", "What do I need before I begin", "Have I done everything needed to start", "Is everything in place to begin", "What should I prepare before onboarding", "Give me a checklist before I start", "What documents or accounts do I need first", "I want to make sure I have everything ready", "What are the things I need to have before setup", "Am I prepared to start the WhatsApp registration" ], "positive_examples": [ "What do I need to have ready before starting", "Is everything prepared to begin", "Give me a pre-setup checklist", "Am I ready to start", "What should I arrange before onboarding" ], "confusing_non_matching_examples": [ "Am I eligible for WhatsApp API? (→ onboarding_eligibility — eligibility is a criteria question, readiness is a 'have I prepared' question)", "Continue my setup (→ onboarding_continue)", "Is my account approved? (→ onboarding_verification_status)" ], "similarity_guidance": "'Ready', 'prepared', 'checklist', 'what do I need', 'before I start' → strong match.", "disambiguation_notes": "Readiness presumes eligibility is confirmed and asks what assets/accounts to have. Eligibility questions contain 'can I', 'am I allowed', 'do I qualify'.", "when_to_use": "User asks for preparation checklist before starting onboarding.", "when_not_to_use": "User already mid-onboarding (use onboarding_continue).", "fallback_behavior": "Keyword: 'ready', 'checklist', 'prepare', 'what do I need'.", "dependency_check": "None." }, { "intent_rule_id": "OR-005", "child_agent_target": "Onboarding Helper", "intent_name": "onboarding_manual_setup", "intent_description": "User explicitly wants to do the setup manually, step-by-step, without automated embedded signup flow.", "routing_priority_weight": 91, "embedding_intent_label": "manual step by step whatsapp business api setup without embedded signup", "semantic_cluster_examples": [ "I want to do the setup manually", "Show me step by step manual setup", "I don't want to use the automatic process", "Guide me through manual registration", "I prefer to configure everything myself", "Manual WhatsApp Business setup process", "I want to do it without the embedded flow", "Walk me through each step manually", "Manual onboarding process", "I will enter all the details myself" ], "positive_examples": [ "I want manual setup", "Guide me manually through the process", "I prefer manual over automated", "Step by step manual registration please", "I do not want embedded signup" ], "confusing_non_matching_examples": [ "I want to do automatic setup (→ onboarding_auto_setup)", "Manual chatbot trigger (→ chatbot_trigger_setup — different domain)" ], "similarity_guidance": "'Manual', 'step by step', 'without automated', 'configure myself' → strong match. Must not match 'manual trigger' in chatbot context — use active child context to disambiguate.", "disambiguation_notes": "If Chatbot Helper is active child, 'manual' → chatbot_trigger_setup. If no active child or Onboarding active → onboarding_manual_setup.", "when_to_use": "User prefers manual registration over guided auto-flow.", "when_not_to_use": "Active child is Chatbot Helper (then manual = chatbot trigger).", "fallback_behavior": "Keyword: 'manual', 'step by step', 'manually', 'without embedded'.", "dependency_check": "None." }, { "intent_rule_id": "OR-006", "child_agent_target": "Onboarding Helper", "intent_name": "onboarding_auto_setup", "intent_description": "User wants to use the automated embedded signup flow for WhatsApp Business API registration.", "routing_priority_weight": 90, "embedding_intent_label": "automatic embedded signup guided whatsapp api registration", "semantic_cluster_examples": [ "I want to use embedded signup", "Automatic WhatsApp setup", "Guide me through the automated process", "Use the auto registration flow", "I want the quick setup option", "The guided automatic setup", "I want to use the wizard for WhatsApp setup", "Show me the automated signup", "Auto onboarding process", "I want the fast automatic registration" ], "positive_examples": [ "I want embedded signup", "Use the automatic setup process", "Quick guided WhatsApp setup", "Auto registration for WhatsApp API", "I want the automated flow" ], "confusing_non_matching_examples": [ "I want manual setup (→ onboarding_manual_setup)", "Is my account auto-approved? (→ onboarding_verification_status)" ], "similarity_guidance": "'Embedded signup', 'auto', 'automatic', 'wizard', 'guided flow' → strong match.", "disambiguation_notes": "Embedded signup is a specific Meta feature. Auto setup ≠ automatic campaign scheduling. Context of 'auto' matters.", "when_to_use": "User explicitly chooses automated registration path.", "when_not_to_use": "User wants manual or is mid-setup already.", "fallback_behavior": "Keyword: 'embedded signup', 'auto', 'automatic setup', 'guided'.", "dependency_check": "None." }, { "intent_rule_id": "OR-007", "child_agent_target": "Onboarding Helper", "intent_name": "onboarding_verification_status", "intent_description": "User wants to check the current approval or verification status of their business account or phone number.", "routing_priority_weight": 89, "embedding_intent_label": "check approval verification status of whatsapp business account or phone number", "semantic_cluster_examples": [ "Is my business verified on Meta", "What is the status of my account approval", "Has my phone number been confirmed", "Is my WhatsApp account approved", "Did Meta approve my registration", "What is my verification status", "Is my business account live", "Has my account been reviewed", "Check if my account is active", "Was my Meta business account verified" ], "positive_examples": [ "Is my business verified", "What is my account approval status", "Has Meta approved my account", "Is my phone number confirmed", "Check my verification status" ], "confusing_non_matching_examples": [ "Am I eligible? (→ onboarding_eligibility — eligibility is pre-application, verification is post-application)", "Campaign status check (→ campaign_status — different domain)" ], "similarity_guidance": "'Verified', 'approved', 'status', 'confirmed', 'live', 'reviewed' in account/business context → strong match.", "disambiguation_notes": "Verification status = post-application approval. Campaign status = campaign delivery status. Must be separated by domain context.", "when_to_use": "User applied for WABA and wants to know if approved.", "when_not_to_use": "User asking about campaign delivery status or template approval status (different domains).", "fallback_behavior": "Keyword: 'verified', 'approved', 'status', 'confirmation'.", "dependency_check": "None, but logically follows onboarding_start." } ], "template": [ { "intent_rule_id": "TR-001", "child_agent_target": "Template Helper", "intent_name": "template_start", "intent_description": "User wants to create a new WhatsApp message template from scratch.", "routing_priority_weight": 90, "embedding_intent_label": "create new whatsapp message template from scratch", "semantic_cluster_examples": [ "I want to create a message template", "How do I make a WhatsApp template", "I need to build a notification template", "Create a new template for my messages", "I want to set up a message format for customers", "Help me draft a new template", "I need something for order update messages", "Create a template for appointment reminders", "I want to make a promotional message template", "How to create a new approved template" ], "positive_examples": [ "Create a new message template", "I need to build a template from scratch", "How do I make a WhatsApp notification template", "I need a template for order confirmations", "Help me create a template" ], "confusing_non_matching_examples": [ "Which template should I use in my campaign? (→ campaign_start or active campaign child — template selection, not template creation)", "Review my existing template (→ template_review)", "Continue working on my template (→ template_continue)" ], "similarity_guidance": "Phrases about creating, building, drafting, making a NEW template → strong match. 'Use template in campaign' → campaign domain, P=80 conflict rule.", "disambiguation_notes": "template_start = creating a new template. Campaign asking 'which template to use' = campaign child task. KEY RULE: if Campaign Helper is active, template questions stay in Campaign.", "when_to_use": "No active template session. User initiates template creation.", "when_not_to_use": "Active Campaign child (template selection within campaign stays with Campaign Helper).", "fallback_behavior": "Keyword: 'template', 'create template', 'message template', 'notification template'.", "dependency_check": "Soft: Onboarding should be complete before creating templates intended for live campaigns." }, { "intent_rule_id": "TR-002", "child_agent_target": "Template Helper", "intent_name": "template_continue", "intent_description": "User has an existing template draft in progress and wants to resume or complete it.", "routing_priority_weight": 89, "embedding_intent_label": "resume or complete existing whatsapp template draft", "semantic_cluster_examples": [ "Continue with my template", "I was building a template, let me resume", "Where did I stop with my template creation", "Finish my template draft", "I need to complete the template I started", "Resume my template work", "I was working on a message template earlier", "Pick up from where I left on the template", "I have an incomplete template", "Continue editing my template" ], "positive_examples": [ "Continue my template creation", "I started a template, let me finish it", "Resume where I left off on the template", "I have an incomplete draft template", "Go back to my template" ], "confusing_non_matching_examples": [ "I want to create a new template (→ template_start)", "Can I improve my template? (→ template_improvement)" ], "similarity_guidance": "'Continue', 'resume', 'left off', 'incomplete', 'finish' with template context → strong match.", "disambiguation_notes": "Past-tense + template context = template_continue. Fresh creation = template_start.", "when_to_use": "Active template session or user signals prior template work.", "when_not_to_use": "No prior template session exists.", "fallback_behavior": "Check session DB for existing template draft. If found, route with sticky bias.", "dependency_check": "None." }, { "intent_rule_id": "TR-003", "child_agent_target": "Template Helper", "intent_name": "template_review", "intent_description": "User wants to review a drafted template to check if it will be approved by Meta/WhatsApp.", "routing_priority_weight": 88, "embedding_intent_label": "review check whatsapp template for approval readiness", "semantic_cluster_examples": [ "Will my template get approved", "Can you review my template", "Check if my template is correct", "Is this template okay to submit", "Does this template meet WhatsApp guidelines", "Please look over my template", "Is my template ready to be approved", "Will Meta approve this message", "Check my template before submission", "Is this format acceptable for WhatsApp" ], "positive_examples": [ "Review my template before I submit", "Will this template be approved", "Check if my template meets guidelines", "Is my template ready", "Can you verify my template" ], "confusing_non_matching_examples": [ "My template was rejected — fix it (→ template_improvement)", "I want to create a new template (→ template_start)" ], "similarity_guidance": "'Review', 'check', 'verify', 'will it be approved', 'is it okay' → strong match.", "disambiguation_notes": "Review = proactive check before submission. Improvement = post-rejection fix. The presence of 'rejected' strongly signals template_improvement.", "when_to_use": "User has a template draft and wants pre-submission review.", "when_not_to_use": "Template already submitted and rejected (use template_improvement).", "fallback_behavior": "Keyword: 'review', 'check template', 'approved', 'guidelines'.", "dependency_check": "None." }, { "intent_rule_id": "TR-004", "child_agent_target": "Template Helper", "intent_name": "template_improvement", "intent_description": "User's template was rejected or needs fixing. They want help improving it to meet approval criteria.", "routing_priority_weight": 87, "embedding_intent_label": "fix rejected template or improve template to meet whatsapp approval criteria", "semantic_cluster_examples": [ "My template was rejected, how do I fix it", "WhatsApp rejected my message template", "How do I improve my template", "My template failed review, what should I change", "Template rejection — how to fix", "Why was my template not approved", "What changes do I need to make to my template", "My template was denied, help me revise it", "How to resubmit a rejected template", "Improve my template so it gets approved" ], "positive_examples": [ "My template got rejected, how do I fix it", "How to improve a rejected template", "WhatsApp denied my template — what to change", "Help me revise my rejected template", "Why was my template rejected" ], "confusing_non_matching_examples": [ "Can you review my template before I submit? (→ template_review — not yet rejected)", "I want to create a new template (→ template_start)" ], "similarity_guidance": "'Rejected', 'denied', 'failed', 'fix', 'revise', 'improve' in template context → strong match.", "disambiguation_notes": "Rejection = template_improvement. Pre-submission review = template_review. These are sequentially distinct.", "when_to_use": "User signals template was rejected or needs fixing.", "when_not_to_use": "Template not yet submitted or never rejected.", "fallback_behavior": "Keyword: 'rejected', 'denied', 'fix template', 'improve'.", "dependency_check": "None." }, { "intent_rule_id": "TR-005", "child_agent_target": "Template Helper", "intent_name": "template_interactive_help", "intent_description": "User wants help creating interactive message templates: list messages, reply button templates, or carousel templates.", "routing_priority_weight": 86, "embedding_intent_label": "create interactive whatsapp template with list message reply buttons or carousel", "semantic_cluster_examples": [ "I want an interactive template with buttons", "How do I make a list message template", "I need a carousel message for my products", "Create a reply button template", "How to build a template with quick reply options", "I want a template where user can select from options", "Interactive message with choices", "WhatsApp template with a dropdown list", "How do I add options to my template", "I need a product selection message template" ], "positive_examples": [ "Help me create an interactive template", "I want a template with quick reply buttons", "How to make a list message", "Create a carousel template for products", "I want users to select options in my message" ], "confusing_non_matching_examples": [ "I want to add a URL button to my template (→ template_button_help — more specific button config)", "I want a chatbot where users pick options (→ chatbot_response_type_help — different domain)" ], "similarity_guidance": "'Interactive', 'list message', 'carousel', 'reply button', 'options in template' → strong match.", "disambiguation_notes": "Interactive template = WhatsApp template with built-in interaction. Chatbot response type = automated bot reply logic. Both involve 'choices' but different domains.", "when_to_use": "User specifically asks for interactive elements in a WhatsApp message template.", "when_not_to_use": "User is asking about chatbot flow response types.", "fallback_behavior": "Keyword: 'interactive', 'list message', 'carousel', 'reply button'.", "dependency_check": "None." }, { "intent_rule_id": "TR-006", "child_agent_target": "Template Helper", "intent_name": "template_button_help", "intent_description": "User needs help configuring specific button types in a message template: URL button, quick reply, call-to-action.", "routing_priority_weight": 85, "embedding_intent_label": "configure url quick reply or call to action button in whatsapp template", "semantic_cluster_examples": [ "How do I add a URL button to my template", "I want to add a quick reply button", "How to configure call to action in template", "Add a website link button to message", "I need a button that opens a URL", "How to add a phone call button to WhatsApp template", "Configure buttons in my message template", "I want users to tap a button to visit my site", "Button configuration in WhatsApp message", "How to set up CTA button in template" ], "positive_examples": [ "Add a URL button to my template", "How to configure quick reply buttons", "I need a call-to-action button in my message", "Button setup for my WhatsApp template", "I want a button that links to my website" ], "confusing_non_matching_examples": [ "I want an interactive template with multiple buttons (→ template_interactive_help — broader scope)", "Add a button to my chatbot flow (→ chatbot_edit — chatbot domain)" ], "similarity_guidance": "'Button', 'URL button', 'quick reply', 'CTA', 'call to action', 'tap to visit' → strong match.", "disambiguation_notes": "Template buttons = static configured buttons in approved template. Chatbot buttons = dynamic response options in bot flow. Active child context resolves overlap.", "when_to_use": "User needs specific button type configuration within a message template.", "when_not_to_use": "User adding buttons to chatbot flow (different child).", "fallback_behavior": "Keyword: 'button', 'URL button', 'quick reply', 'CTA', 'call to action'.", "dependency_check": "None." } ], "campaign": [ { "intent_rule_id": "CR-001", "child_agent_target": "Campaign Helper", "intent_name": "campaign_start", "intent_description": "User wants to create and launch a new WhatsApp broadcast campaign to send messages to multiple contacts.", "routing_priority_weight": 88, "embedding_intent_label": "create new whatsapp broadcast campaign to send messages to many contacts", "semantic_cluster_examples": [ "I want to send a message to all my customers", "How do I run a WhatsApp campaign", "Create a broadcast for my sale offer", "I want to send offers to many people on WhatsApp", "Launch a bulk message campaign", "How to send promotional messages to my contact list", "I want to reach out to all my subscribers", "Start a new campaign to announce my product", "How do I send a broadcast message", "Set up a marketing campaign on WhatsApp" ], "positive_examples": [ "I want to run a WhatsApp campaign", "Create a broadcast to send to all my contacts", "I want to send offers to many customers", "Launch a promotional campaign", "How to start a campaign on WhatsApp" ], "confusing_non_matching_examples": [ "Create a template for my campaign (→ template_start — template creation is prerequisite, not campaign start)", "Check my campaign status (→ campaign_status)", "My broadcast is stuck (→ campaign_troubleshooting)" ], "similarity_guidance": "'Broadcast', 'bulk message', 'send to all', 'mass message', 'campaign' with fresh context → strong match.", "disambiguation_notes": "CRITICAL: campaign_start ≠ template_start. If user says 'create template FOR campaign', route to template_start first, queue campaign. If user says 'create campaign WITH existing template', route to campaign_start directly.", "when_to_use": "User wants to create and launch a new campaign. Template dependency must be checked.", "when_not_to_use": "Active campaign session exists (use campaign_continue). User wants to create template (use template_start).", "fallback_behavior": "Keyword: 'campaign', 'broadcast', 'bulk', 'send to all'.", "dependency_check": "HARD: Onboarding must be complete. Template must exist and be approved." }, { "intent_rule_id": "CR-002", "child_agent_target": "Campaign Helper", "intent_name": "campaign_continue", "intent_description": "User has an existing campaign setup in progress and wants to resume it.", "routing_priority_weight": 87, "embedding_intent_label": "resume incomplete campaign setup or continue campaign configuration", "semantic_cluster_examples": [ "Continue with my campaign setup", "I was setting up a campaign, let me resume", "Finish my campaign configuration", "Where did I stop with my campaign", "I need to complete the campaign I started", "Resume my broadcast setup", "I had started a campaign, what is next", "Pick up where I left off on the campaign", "I have an incomplete campaign", "Continue editing my campaign" ], "positive_examples": [ "Continue my campaign setup", "I started setting up a campaign", "Resume the campaign I was working on", "Finish my incomplete campaign", "What is the next step in my campaign" ], "confusing_non_matching_examples": [ "Create a new campaign (→ campaign_start)", "What is my campaign status? (→ campaign_status)" ], "similarity_guidance": "'Continue', 'resume', 'left off', 'incomplete', 'next step' with campaign context → strong match.", "disambiguation_notes": "campaign_continue implies prior progress. campaign_start implies no prior campaign.", "when_to_use": "Active campaign session or user signals prior progress.", "when_not_to_use": "No prior campaign session exists.", "fallback_behavior": "Check session DB for existing campaign draft.", "dependency_check": "HARD: Onboarding must be complete." }, { "intent_rule_id": "CR-003", "child_agent_target": "Campaign Helper", "intent_name": "campaign_status", "intent_description": "User wants to check the current state of their campaign — whether it is active, scheduled, paused, or completed.", "routing_priority_weight": 86, "embedding_intent_label": "check current state status of existing whatsapp campaign running paused completed", "semantic_cluster_examples": [ "What is the status of my campaign", "Is my campaign running", "Is my broadcast active", "Is my campaign paused or live", "What is happening with my campaign", "Check my campaign current state", "Is my campaign still going", "My campaign status please", "Is the broadcast live", "Did my campaign get sent" ], "positive_examples": [ "What is my campaign status", "Is my campaign running", "Check if my broadcast is active", "Has my campaign been sent", "Is the campaign live or paused" ], "confusing_non_matching_examples": [ "How did my campaign perform? (→ campaign_analytics — performance metrics vs current state)", "Is my WhatsApp account verified? (→ onboarding_verification_status — different domain)" ], "similarity_guidance": "'Status', 'running', 'active', 'paused', 'current state', 'is it live' → strong match for campaign domain.", "disambiguation_notes": "campaign_status = 'is it running right now'. campaign_analytics = 'how well did it do'. Both involve 'status' word — discriminate by performance/metrics language.", "when_to_use": "User asks about operational state of an existing campaign.", "when_not_to_use": "User asks about delivery rates, read rates, metrics (→ campaign_analytics).", "fallback_behavior": "Keyword: 'status', 'running', 'active', 'paused'.", "dependency_check": "None — status check on any campaign." }, { "intent_rule_id": "CR-004", "child_agent_target": "Campaign Helper", "intent_name": "campaign_analytics", "intent_description": "User wants to see performance metrics for their campaign: delivery rate, read rate, open rate, click rate, or failed count.", "routing_priority_weight": 85, "embedding_intent_label": "view campaign performance metrics delivery read rate analytics results", "semantic_cluster_examples": [ "How did my campaign perform", "What is my campaign delivery rate", "How many people read my message", "Show me campaign analytics", "What is the open rate of my broadcast", "How many messages were delivered", "Campaign results and statistics", "What percentage of contacts received my message", "How effective was my campaign", "Show me the read rate for my broadcast" ], "positive_examples": [ "Show me my campaign analytics", "What is the delivery rate for my campaign", "How many people opened my broadcast", "Campaign performance report please", "What was the read rate for my last campaign" ], "confusing_non_matching_examples": [ "Is my campaign running? (→ campaign_status — operational state, not performance metrics)", "My campaign is stuck (→ campaign_troubleshooting)" ], "similarity_guidance": "'Analytics', 'performance', 'delivery rate', 'read rate', 'results', 'statistics', 'how many' → strong match.", "disambiguation_notes": "campaign_analytics = quantitative performance review. campaign_status = binary state check. Presence of rate/percentage/count language → analytics.", "when_to_use": "User wants numerical performance data.", "when_not_to_use": "User asks if campaign is currently running (→ campaign_status).", "fallback_behavior": "Keyword: 'analytics', 'delivery rate', 'read rate', 'results'.", "dependency_check": "None — analytics on any past/current campaign." }, { "intent_rule_id": "CR-005", "child_agent_target": "Campaign Helper", "intent_name": "campaign_edit", "intent_description": "User wants to modify an existing campaign: change its name, audience, template, timing, or message content.", "routing_priority_weight": 84, "embedding_intent_label": "modify update or edit existing whatsapp campaign settings or content", "semantic_cluster_examples": [ "I need to change my campaign", "Update the message in my campaign", "Edit the audience for my broadcast", "Change the timing of my campaign", "Modify my campaign before it sends", "I want to update my campaign content", "Can I change the template in my campaign", "Edit campaign settings", "Update my broadcast target list", "Change my campaign schedule" ], "positive_examples": [ "Edit my campaign", "I need to change the audience in my campaign", "Update my campaign message", "Modify the campaign I already set up", "Change the timing of my broadcast" ], "confusing_non_matching_examples": [ "My campaign is not working (→ campaign_troubleshooting)", "Edit my chatbot flow (→ chatbot_edit — different domain)" ], "similarity_guidance": "'Edit', 'change', 'update', 'modify' in campaign context → strong match.", "disambiguation_notes": "campaign_edit = intentional modification. campaign_troubleshooting = something is broken/failing. Active child context resolves 'edit' ambiguity against chatbot_edit.", "when_to_use": "User wants to update a campaign that exists and is not broken.", "when_not_to_use": "Campaign is failing/stuck (→ campaign_troubleshooting).", "fallback_behavior": "Keyword: 'edit', 'change', 'update', 'modify' with campaign.", "dependency_check": "None." }, { "intent_rule_id": "CR-006", "child_agent_target": "Campaign Helper", "intent_name": "campaign_troubleshooting", "intent_description": "User's campaign has an issue: messages not sending, broadcast stuck, delivery failure, or campaign not starting.", "routing_priority_weight": 83, "embedding_intent_label": "fix campaign not sending broadcast stuck messages failing delivery error", "semantic_cluster_examples": [ "My campaign is not sending messages", "Why is my broadcast stuck", "Campaign failed to deliver", "Messages are not being sent in my campaign", "My broadcast is not going through", "Campaign stuck — how to fix", "Why are my campaign messages failing", "Delivery failure in campaign", "My campaign is not working", "Help my broadcast is broken" ], "positive_examples": [ "Why is my broadcast stuck", "My campaign is not sending", "Campaign delivery failure", "Messages not going through in my campaign", "Help, my campaign is broken" ], "confusing_non_matching_examples": [ "My bot is not replying (→ chatbot_troubleshooting — different domain)", "Campaign performance is low (→ campaign_analytics — performance review, not failure)" ], "similarity_guidance": "'Not sending', 'stuck', 'failing', 'not working', 'broken' in campaign context → strong match.", "disambiguation_notes": "campaign_troubleshooting = technical failure. campaign_analytics = performance analysis. campaign_status = state check. Language of 'not working', 'stuck', 'failed' → troubleshooting.", "when_to_use": "User reports campaign failure or inability to send.", "when_not_to_use": "Campaign is running but has low metrics (→ campaign_analytics).", "fallback_behavior": "Keyword: 'not sending', 'stuck', 'failed', 'not working', 'broken'.", "dependency_check": "None." }, { "intent_rule_id": "CR-007", "child_agent_target": "Campaign Helper", "intent_name": "campaign_schedule_help", "intent_description": "User wants help scheduling a campaign for a specific date/time or wants to understand timing options.", "routing_priority_weight": 82, "embedding_intent_label": "schedule whatsapp campaign for specific time or set campaign send timing", "semantic_cluster_examples": [ "Schedule my campaign for tomorrow morning", "When should I send my broadcast", "How to set the timing for my campaign", "I want to send the campaign at 10 AM", "Schedule the broadcast for next Monday", "Set campaign to send at a specific time", "How do I delay the campaign send", "I want to schedule the campaign", "Send the campaign later not now", "What time should I schedule my broadcast" ], "positive_examples": [ "Schedule my campaign for next week", "How to set campaign send timing", "I want to delay the broadcast", "Send campaign at 9 AM tomorrow", "Set the timing for my campaign" ], "confusing_non_matching_examples": [ "Schedule my chatbot trigger (→ chatbot_trigger_setup — different domain)", "Campaign is running but not delivering (→ campaign_troubleshooting)" ], "similarity_guidance": "'Schedule', 'timing', 'send at', 'set time', 'delay', 'later' with campaign context → strong match.", "disambiguation_notes": "campaign_schedule_help = when to send campaign. chatbot_trigger_setup = when to activate bot. 'Schedule' alone with no active child → clarify.", "when_to_use": "User wants to configure campaign timing.", "when_not_to_use": "User asking about chatbot trigger scheduling.", "fallback_behavior": "Keyword: 'schedule', 'timing', 'send at', 'send later'.", "dependency_check": "HARD: Onboarding complete, template approved." } ], "chatbot": [ { "intent_rule_id": "CB-001", "child_agent_target": "Chatbot Helper", "intent_name": "chatbot_start", "intent_description": "User wants to create a new chatbot or automated reply flow for WhatsApp from scratch.", "routing_priority_weight": 85, "embedding_intent_label": "create new whatsapp chatbot automated reply flow from scratch", "semantic_cluster_examples": [ "I want to build a chatbot", "Create a WhatsApp bot for my business", "Set up automated replies on WhatsApp", "I want a bot that answers customer questions", "Build an automated WhatsApp assistant", "How do I create a chatbot", "I want to automate my WhatsApp responses", "Set up a bot flow for customer support", "Build a WhatsApp automation", "I need a bot that handles common questions" ], "positive_examples": [ "I want to create a chatbot", "Build a WhatsApp bot", "Set up automated replies for my WhatsApp", "Help me build a bot flow", "I want automated customer support on WhatsApp" ], "confusing_non_matching_examples": [ "I already started my bot, continue (→ chatbot_continue)", "Publish my existing bot (→ chatbot_publish)", "My bot is not replying (→ chatbot_troubleshooting)" ], "similarity_guidance": "'Build', 'create', 'set up', 'automated replies', 'bot' with fresh context → strong match.", "disambiguation_notes": "chatbot_start = new bot. chatbot_continue = existing in-progress bot. Presence of 'already', 'existing', 'resume' → chatbot_continue.", "when_to_use": "User initiates chatbot creation for first time.", "when_not_to_use": "Active chatbot session exists.", "fallback_behavior": "Keyword: 'chatbot', 'bot', 'automated reply', 'flow builder'.", "dependency_check": "Soft: Onboarding recommended but not hard-blocked." }, { "intent_rule_id": "CB-002", "child_agent_target": "Chatbot Helper", "intent_name": "chatbot_continue", "intent_description": "User has an existing chatbot flow draft and wants to resume building or configuring it.", "routing_priority_weight": 84, "embedding_intent_label": "resume existing chatbot flow configuration in progress", "semantic_cluster_examples": [ "Continue building my chatbot", "I was setting up my bot flow", "Resume chatbot configuration", "I need to finish my bot setup", "Where did I stop with my chatbot", "Continue from where I left on the bot", "Pick up my chatbot flow setup", "I have an incomplete bot flow", "Continue my WhatsApp automation", "Go back to my chatbot setup" ], "positive_examples": [ "Continue my chatbot setup", "Resume building my bot flow", "I started a bot, let me finish", "Continue with my WhatsApp automation", "Where did I stop on my chatbot" ], "confusing_non_matching_examples": [ "Create a new chatbot (→ chatbot_start)", "Publish my bot (→ chatbot_publish)" ], "similarity_guidance": "Past-tense + bot/chatbot context → strong match.", "disambiguation_notes": "Same pattern as other 'continue' intents — past-tense signals are key.", "when_to_use": "Active chatbot session or user signals prior progress.", "when_not_to_use": "No prior bot session exists.", "fallback_behavior": "Check session DB for existing chatbot draft.", "dependency_check": "None." }, { "intent_rule_id": "CB-003", "child_agent_target": "Chatbot Helper", "intent_name": "chatbot_publish", "intent_description": "User wants to publish their chatbot flow to make it live and active on WhatsApp.", "routing_priority_weight": 83, "embedding_intent_label": "publish activate make chatbot flow live on whatsapp", "semantic_cluster_examples": [ "Publish my chatbot", "Make my bot live", "Activate my WhatsApp chatbot", "How do I go live with my bot", "Enable my chatbot", "Deploy my bot flow to WhatsApp", "I want my chatbot to start working", "Launch my bot", "Turn on my chatbot", "How do I activate my bot" ], "positive_examples": [ "Publish my chatbot", "Make my bot live", "How do I go live with my chatbot", "Activate my WhatsApp bot", "Deploy my bot flow" ], "confusing_non_matching_examples": [ "Send my campaign now (→ campaign_start — publish ≠ campaign send)", "Submit my template for approval (→ template_review — template submission, not chatbot publish)" ], "similarity_guidance": "'Publish', 'make live', 'activate', 'deploy', 'turn on', 'launch' with bot/chatbot context → strong match.", "disambiguation_notes": "CRITICAL: chatbot_publish ≠ campaign send. 'Publish it' during active Chatbot child → chatbot_publish. P=75 conflict rule enforced.", "when_to_use": "User has a complete bot flow and wants to activate it.", "when_not_to_use": "User sending a campaign (campaign_start/campaign_continue).", "fallback_behavior": "Keyword: 'publish', 'go live', 'activate bot', 'deploy'.", "dependency_check": "Soft: Onboarding recommended before publishing." }, { "intent_rule_id": "CB-004", "child_agent_target": "Chatbot Helper", "intent_name": "chatbot_trigger_setup", "intent_description": "User wants to configure keyword triggers that activate the chatbot when users send specific words.", "routing_priority_weight": 82, "embedding_intent_label": "configure keyword trigger to activate chatbot when user sends specific word", "semantic_cluster_examples": [ "How do I set a keyword trigger for my bot", "What keyword should start my chatbot", "Set up a trigger word for my bot", "I want my bot to reply when user types a word", "Configure the keyword that starts my chatbot", "How to make bot reply to specific words", "Keyword trigger setup for WhatsApp bot", "I want bot to activate on keyword", "Set the trigger phrase for my chatbot", "When user says pricing, my bot should reply" ], "positive_examples": [ "Set up a keyword trigger for my chatbot", "How to configure bot trigger words", "I want my bot to activate on keyword", "Set trigger phrase for my chatbot", "Configure keyword that starts my bot" ], "confusing_non_matching_examples": [ "What keywords should I avoid in templates? (→ template_review — template guidelines, not chatbot trigger)", "Manual setup please (→ onboarding_manual_setup — if no active chatbot child)" ], "similarity_guidance": "'Keyword trigger', 'trigger word', 'bot activates on', 'reply to specific word' → strong match.", "disambiguation_notes": "CRITICAL: 'keyword' in chatbot context = trigger setup. 'keyword' in routing logic = different concept. P=78 rule: 'keyword' in active Chatbot child → chatbot_trigger_setup.", "when_to_use": "User configuring what words activate their chatbot.", "when_not_to_use": "User not discussing chatbot automation.", "fallback_behavior": "Keyword: 'keyword trigger', 'trigger word', 'activate on keyword'.", "dependency_check": "None — chatbot must exist or be created first." }, { "intent_rule_id": "CB-005", "child_agent_target": "Chatbot Helper", "intent_name": "chatbot_edit", "intent_description": "User wants to modify an existing chatbot flow: change a node, update a response, add a new branch.", "routing_priority_weight": 81, "embedding_intent_label": "modify update edit existing chatbot flow node or response", "semantic_cluster_examples": [ "I want to edit my chatbot flow", "Change my bot response", "Update my chatbot", "Modify my bot flow", "I need to change what my bot says", "Edit a node in my chatbot", "Add a new branch to my bot flow", "Change the response in step 3 of my bot", "Update my chatbot flow configuration", "I need to fix something in my bot" ], "positive_examples": [ "Edit my chatbot flow", "Change what my bot says", "Update a node in my chatbot", "Modify my WhatsApp bot", "Add a new branch to my bot" ], "confusing_non_matching_examples": [ "My bot is not working (→ chatbot_troubleshooting — broken vs edit intention)", "Edit my campaign (→ campaign_edit — different domain)" ], "similarity_guidance": "'Edit', 'change', 'update', 'modify' with chatbot/bot context → strong match.", "disambiguation_notes": "chatbot_edit = intentional modification. chatbot_troubleshooting = something broken. Active child context disambiguates edit vs campaign_edit.", "when_to_use": "User deliberately modifies an existing chatbot.", "when_not_to_use": "Bot is broken/failing (→ chatbot_troubleshooting).", "fallback_behavior": "Keyword: 'edit bot', 'change bot', 'update chatbot'.", "dependency_check": "None." }, { "intent_rule_id": "CB-006", "child_agent_target": "Chatbot Helper", "intent_name": "chatbot_troubleshooting", "intent_description": "User's chatbot is not working: not replying, giving wrong answers, or triggering incorrectly.", "routing_priority_weight": 80, "embedding_intent_label": "fix chatbot not replying wrong answers not triggering correctly broken", "semantic_cluster_examples": [ "My bot is not replying", "My chatbot is not working", "Bot not responding to customers", "My bot gives wrong answers", "Chatbot not triggering", "My bot is silent", "Bot is live but not responding", "Chatbot is broken", "My WhatsApp bot is not working properly", "Bot replies with wrong information" ], "positive_examples": [ "My bot is not replying", "Chatbot not working", "Bot gives wrong answers", "My chatbot is not triggering", "Help, my bot is broken" ], "confusing_non_matching_examples": [ "My campaign is not sending (→ campaign_troubleshooting — different domain)", "I want to edit my bot (→ chatbot_edit — intentional change, not failure)" ], "similarity_guidance": "'Not replying', 'not working', 'wrong answers', 'not triggering', 'broken', 'silent' with bot context → strong match.", "disambiguation_notes": "chatbot_troubleshooting = failure state. chatbot_edit = intentional update. Both use 'fix' — distinguish by context: 'broken/not working' vs 'change/update'.", "when_to_use": "User reports chatbot failure.", "when_not_to_use": "User is intentionally updating bot (→ chatbot_edit).", "fallback_behavior": "Keyword: 'not replying', 'not working', 'broken', 'not responding'.", "dependency_check": "None." }, { "intent_rule_id": "CB-007", "child_agent_target": "Chatbot Helper", "intent_name": "chatbot_response_type_help", "intent_description": "User wants to understand or configure different response types their chatbot can use: text, media, buttons, list, or flow.", "routing_priority_weight": 79, "embedding_intent_label": "configure chatbot response types text media button list or flow nodes", "semantic_cluster_examples": [ "What types of responses can my chatbot send", "How do I set up a button response in my bot", "Can my bot send images", "How to configure different response types", "I want my bot to reply with a list", "Can the bot send media files", "How to make bot show a menu", "Response type setup in chatbot", "I want bot to use button replies", "What formats can my bot respond in" ], "positive_examples": [ "What response types can my bot use", "How to set up button responses in chatbot", "Can my bot send images or videos", "Configure different response types in bot", "How to make bot reply with a menu" ], "confusing_non_matching_examples": [ "I want an interactive message template (→ template_interactive_help — template domain)", "My bot is not replying (→ chatbot_troubleshooting)" ], "similarity_guidance": "'Response types', 'button reply', 'bot sends images', 'menu in bot', 'formats' → strong match.", "disambiguation_notes": "chatbot_response_type_help = what formats the bot can use. template_interactive_help = interactive elements in a WhatsApp message template. Both involve 'choices' — chatbot = dynamic runtime, template = static approved message.", "when_to_use": "User configuring chatbot node response format.", "when_not_to_use": "User asking about interactive template message format.", "fallback_behavior": "Keyword: 'response type', 'button reply', 'bot menu', 'media response'.", "dependency_check": "None." } ], "master_cross_flow": [ { "intent_rule_id": "MX-001", "child_agent_target": null, "intent_name": "multi_intent_request", "intent_description": "User explicitly mentions TWO OR MORE separate tasks across different child agent domains in one message.", "routing_priority_weight": 99, "embedding_intent_label": "user requests multiple distinct tasks across different child agents simultaneously", "semantic_cluster_examples": [ "Help me complete onboarding and then create a template", "I need to set up my WhatsApp and build a chatbot", "Create a template and use it in a campaign", "I want onboarding, chatbot, and campaign all set up", "My bot is not working and I also need to run a campaign", "Complete the setup and send a broadcast", "I need template creation and campaign together", "Set up WhatsApp account and then create a bot", "I want to do campaign and chatbot both", "Finish onboarding then help me with templates" ], "positive_examples": [ "Help me with onboarding and template creation", "I need campaign and chatbot both", "Create template and campaign together", "Finish my setup and start a campaign", "I want to set up WhatsApp and build a bot" ], "confusing_non_matching_examples": [ "Just create a campaign (→ campaign_start — single intent)" ], "similarity_guidance": "Presence of connector words ('and', 'then', 'also', 'both') linking two different domain terms → strong multi-intent signal.", "disambiguation_notes": "Multi-intent requires TWO different domain targets. 'Template and campaign' = multi-intent. 'Template button and quick reply' = single intent (both template domain).", "when_to_use": "Exactly two or more cross-domain tasks explicitly stated.", "when_not_to_use": "Single domain with compound request.", "fallback_behavior": "If only one domain clearly dominant, route to that as primary.", "dependency_check": "Apply dependency rules per queued task." }, { "intent_rule_id": "MX-002", "child_agent_target": null, "intent_name": "switch_agent_request", "intent_description": "User explicitly requests to switch to a different child agent domain mid-session.", "routing_priority_weight": 98, "embedding_intent_label": "user explicitly requests switching to different child agent domain", "semantic_cluster_examples": [ "Switch to template section", "Take me to campaign setup", "I want to go to the chatbot helper", "Move me to onboarding", "Let me switch to template creation", "I want to talk about campaigns instead", "Take me to the chatbot section", "Switch topics to template", "I want to work on campaigns now", "Move to a different section" ], "positive_examples": [ "Switch to template", "Take me to campaign setup", "I want to go to chatbot now", "Move me to onboarding section", "Switch to a different topic" ], "confusing_non_matching_examples": [ "Go back (→ return_to_previous_agent)" ], "similarity_guidance": "'Switch', 'take me to', 'move to', 'I want to go to' + domain name → strong match.", "disambiguation_notes": "switch_agent_request = go to NEW domain. return_to_previous_agent = go BACK to prior domain. Directional language distinguishes them.", "when_to_use": "User explicitly names a different domain to move to.", "when_not_to_use": "User wants to go back to previous (→ return_to_previous_agent).", "fallback_behavior": "If domain name not parseable, ask: which section?", "dependency_check": "Apply dependency check for target domain." }, { "intent_rule_id": "MX-003", "child_agent_target": null, "intent_name": "return_to_previous_agent", "intent_description": "User wants to return to a previously active child agent or go back to the master menu.", "routing_priority_weight": 97, "embedding_intent_label": "return to previous agent or go back to master menu", "semantic_cluster_examples": [ "Go back", "Take me back to where I was", "Return to previous section", "I want to go back", "Back to the main menu", "Return to the last thing I was doing", "Go back to my campaign", "I want to return to onboarding", "Not this, go back", "Return to master" ], "positive_examples": [ "Go back", "Take me back to where I was", "Return to previous section", "Back to the last thing I was doing", "I want to return to my campaign" ], "confusing_non_matching_examples": [ "Switch to template (→ switch_agent_request — forward navigation, not return)" ], "similarity_guidance": "'Go back', 'return', 'previous', 'last thing I was doing' → strong match.", "disambiguation_notes": "Backward navigation = return_to_previous_agent. Forward navigation to new domain = switch_agent_request.", "when_to_use": "User navigates backward or wants master-level menu.", "when_not_to_use": "User navigates to a new domain.", "fallback_behavior": "Return to last paused child agent. If none, present master options.", "dependency_check": "None." }, { "intent_rule_id": "MX-004", "child_agent_target": null, "intent_name": "dependency_resolution_request", "intent_description": "User asks what needs to be done first, what prerequisites exist, or what the correct order of operations is.", "routing_priority_weight": 96, "embedding_intent_label": "ask about prerequisites order of operations what to do first dependency chain", "semantic_cluster_examples": [ "What do I need to do first", "What are the prerequisites", "What is the correct order of setup", "Which step comes before this one", "What should I complete first", "Is there something I need to do before campaign", "What depends on what", "Tell me the order of operations", "What comes first — template or campaign", "What prerequisite is needed before I start" ], "positive_examples": [ "What do I need to complete first", "What are the prerequisites for campaign", "What order should I follow", "What comes before template creation", "Is onboarding required before campaign" ], "confusing_non_matching_examples": [ "Am I ready to start? (→ onboarding_readiness — specific to onboarding checklist)" ], "similarity_guidance": "'Prerequisites', 'order', 'first', 'before', 'comes before', 'depends on' → strong match.", "disambiguation_notes": "dependency_resolution_request = cross-domain order question. onboarding_readiness = specific to onboarding pre-check. These are semantically close — disambiguate by domain specificity.", "when_to_use": "User asks about cross-domain dependencies.", "when_not_to_use": "User asking specifically about onboarding prerequisites only.", "fallback_behavior": "Explain dependency chain: onboarding → template → campaign.", "dependency_check": "None." }, { "intent_rule_id": "MX-005", "child_agent_target": null, "intent_name": "ambiguous_business_help", "intent_description": "User asks for generic help about their WhatsApp business setup without specifying any domain.", "routing_priority_weight": 10, "embedding_intent_label": "generic vague help request about whatsapp business no specific domain", "semantic_cluster_examples": [ "Help", "I need help", "I have a problem", "Not working", "Issue with my WhatsApp", "Something is wrong", "Help me please", "I have a question", "I need assistance", "I am stuck" ], "positive_examples": [ "I need help", "Something is not working", "I have an issue", "Help please", "I am stuck" ], "confusing_non_matching_examples": [ "My bot is not working (→ chatbot_troubleshooting — specific domain)", "My campaign is stuck (→ campaign_troubleshooting — specific domain)" ], "similarity_guidance": "Generic help language with NO domain specifier → falls to this intent as last resort.", "disambiguation_notes": "This intent is the catch-all fallback. If active child exists, forward to active child first (P=85 rule). This only fires when both embedding AND keyword fail to identify a specific domain.", "when_to_use": "Last resort — no domain identified, no active child.", "when_not_to_use": "Any other specific intent matches.", "fallback_behavior": "Present master-level options: onboarding, template, campaign, chatbot.", "dependency_check": "None." } ] }, "INTENT_DISAMBIGUATION_RULES": [ { "rule_id": "DISAMB-001", "competing_intents": ["template_start", "campaign_start"], "conflict_scenario": "User says 'create template' but active child is Campaign Helper", "resolution_logic": "P=80 conflict rule: if Campaign Helper is active child AND user says 'template', interpret as template SELECTION within campaign (not template CREATION). Route stays Campaign Helper.", "override_condition": "If user says 'I want to CREATE a NEW template' or 'build a template from scratch' — explicitly override to template_start, pause campaign." }, { "rule_id": "DISAMB-002", "competing_intents": ["chatbot_trigger_setup", "routing_keyword_fallback"], "conflict_scenario": "User says 'keyword' — could mean chatbot trigger keyword OR generic keyword rule matching", "resolution_logic": "P=78 rule: if Chatbot Helper is active child, 'keyword' → chatbot_trigger_setup. If no active child, clarify.", "override_condition": "Never let generic keyword routing fire over chatbot_trigger_setup when Chatbot is active." }, { "rule_id": "DISAMB-003", "competing_intents": ["onboarding_eligibility", "onboarding_readiness"], "conflict_scenario": "User asks 'am I ready?' — eligibility (can I?) vs readiness (have I done prep?)", "resolution_logic": "Eligibility = 'can my business/number qualify'. Readiness = 'have I completed prerequisites'. Presence of 'qualify', 'allowed', 'my business type' → eligibility. Presence of 'checklist', 'prepared', 'what do I need' → readiness.", "override_condition": "Active context onboarding-active present → if mid-flow, forward to ask_eligibility_mid_flow child intent." }, { "rule_id": "DISAMB-004", "competing_intents": ["campaign_analytics", "campaign_status"], "conflict_scenario": "User asks about 'campaign status' — binary state vs performance metrics", "resolution_logic": "Presence of 'rate', 'percentage', 'how many', 'delivered', 'read', 'clicked' → campaign_analytics. Presence of 'running', 'active', 'paused', 'is it live' → campaign_status.", "override_condition": "No override — strictly semantic." }, { "rule_id": "DISAMB-005", "competing_intents": ["chatbot_publish", "campaign_start"], "conflict_scenario": "'Publish it' or 'send it' could mean publish chatbot OR send campaign", "resolution_logic": "P=75 rule: if Chatbot Helper is active, 'publish it' → chatbot_publish. If Campaign Helper is active, 'send it' → campaign_start. Pronoun 'it' resolved by active child context.", "override_condition": "No active child: clarify which action user means." }, { "rule_id": "DISAMB-006", "competing_intents": ["onboarding_manual_setup", "chatbot_trigger_setup"], "conflict_scenario": "User says 'manual' — manual onboarding setup vs manual chatbot trigger", "resolution_logic": "Active child = Chatbot Helper → chatbot_trigger_setup. Active child = Onboarding Helper or no active child → onboarding_manual_setup. If truly ambiguous → ASK_MINIMAL_CLARIFICATION.", "override_condition": "Active child takes precedence over ambiguous word matching." }, { "rule_id": "DISAMB-007", "competing_intents": ["template_interactive_help", "chatbot_response_type_help"], "conflict_scenario": "User wants 'options for customers to choose from' — template interactive vs chatbot response type", "resolution_logic": "Context of 'template', 'message format', 'approved message' → template_interactive_help. Context of 'bot flow', 'automated reply', 'when bot responds' → chatbot_response_type_help.", "override_condition": "Active child determines winner in tie." }, { "rule_id": "DISAMB-008", "competing_intents": ["campaign_schedule_help", "chatbot_trigger_setup"], "conflict_scenario": "User says 'schedule' — campaign scheduling vs chatbot scheduled trigger", "resolution_logic": "Active child = Campaign → campaign_schedule_help. Active child = Chatbot → chatbot_trigger_setup. No active child → clarify.", "override_condition": "Time-of-day language ('send at 10 AM', 'tomorrow morning') → campaign_schedule_help even without active child." } ], "INTENT_SCORING_AND_PRIORITY_LOGIC": { "description": "Exact scoring formula and priority hierarchy for master-level routing decisions.", "scoring_formula": { "raw_embedding_score": "cosine_similarity(embed(userText), intent_centroid)", "context_boosted_score": "raw_embedding_score + (active_context_boost * 0.12 if intent belongs to active child) + (sticky_bias * 0.10 if active child matches target and score is top)", "final_score": "context_boosted_score" }, "priority_tiers": [ { "tier": 1, "name": "High-confidence single intent", "condition": "top-1 score >= 0.75", "action": "Route immediately to top-1 intent's child agent" }, { "tier": 2, "name": "Medium-confidence with context", "condition": "top-1 score 0.62–0.74", "action": "Route to top-1. If active child exists and score gap < 0.05, apply sticky bias and re-evaluate." }, { "tier": 3, "name": "Multi-intent detection", "condition": "top-1 >= 0.58 AND top-2 >= 0.58 AND different child targets AND score gap <= 0.06", "action": "MULTI_INTENT: route primary, queue secondary" }, { "tier": 4, "name": "Low confidence — try keyword", "condition": "top-1 score 0.50–0.61", "action": "Fall through to keyword rule evaluation. Use embedding score as a tie-breaker." }, { "tier": 5, "name": "Very low — clarify", "condition": "top-1 score < 0.50 AND keyword rules also fail", "action": "ASK_MINIMAL_CLARIFICATION. Present max 3 options." } ], "tie_break_rules": [ "1. Active child agent's intents get +0.12 boost", "2. If tie persists: use expected_next_step context (session's last bot question hints at expected slot type)", "3. If tie persists: route to higher routing_priority_weight child agent", "4. Last resort: route to active child if one exists, else clarify" ] }, "KEYWORD_FALLBACK_POLICY": { "description": "Keyword rules remain in the DB as MasterRouteRules. They fire ONLY when embedding confidence is below threshold.", "activation_condition": "top-1 embedding score < intent_confidence_threshold (0.62)", "priority_rule": "Embedding intent routing OVERRIDES keyword match when embedding score >= 0.62, even if keyword also matches.", "exception": "If embedding score >= 0.62 and keyword rule disagrees: EMBEDDING WINS. Log the discrepancy for retraining.", "keyword_rule_priority_bands": { "P_115_to_95": "Troubleshoot overrides and primary domain keywords — still valid as fallback", "P_80_to_75": "Conflict resolution keyword rules — these COMPLEMENT embedding (not replace)", "P_85": "Active child continuation — this is also handled by sticky_agent_bias in embedding layer", "P_10": "Clarification fallback — fires only when both embedding and keyword fail" } }, "CONTEXT_OVERRIDE_POLICY": { "description": "How active child context and expected-next-step context modify intent routing decisions.", "rules": [ { "policy_id": "COP-001", "name": "Active Child Sticky Routing", "condition": "active_child_agent is set AND incoming intent belongs to same child", "action": "Apply sticky_agent_bias (+0.10). Route to active child.", "priority": "Fires before multi-intent check" }, { "policy_id": "COP-002", "name": "Conflict Resolution Override", "condition": "active_child_agent is set AND incoming keyword matches a DIFFERENT child's domain BUT conflict rule exists", "action": "Apply conflict rule (P=75/78/80). Keep active child. Do NOT switch.", "affected_intents": ["template in campaign", "keyword in chatbot", "publish in chatbot"], "priority": "Fires before domain keyword routing" }, { "policy_id": "COP-003", "name": "Explicit Switch Override", "condition": "switch_agent_request intent detected with score >= 0.62", "action": "PRESERVE_CONTEXT_AND_SWITCH. Pause current child, activate new child.", "priority": "Overrides active child sticky routing" }, { "policy_id": "COP-004", "name": "Expected Next Step Context", "condition": "session.expected_next_action is set (e.g., 'awaiting_phone_number_id')", "action": "Treat incoming message as slot response. Forward to active child as parameter fill. Skip intent matching for this turn.", "priority": "Highest — fires before embedding scoring when expected_next_action is set" }, { "policy_id": "COP-005", "name": "Dependency Block", "condition": "Routing to campaign or chatbot but dependency_status.onboarding != COMPLETED", "action": "RESOLVE_DEPENDENCY_FIRST. Route to Onboarding Helper. Queue the original target task.", "priority": "P=110 — fires after intent detection but before child handoff" }, { "policy_id": "COP-006", "name": "Task Completion Context Clear", "condition": "Child agent emits COMPLETED status", "action": "Clear active_child_agent. Set child_agent_status_map[child] = COMPLETED. Return control to master. Re-enable full embedding scoring for next turn.", "priority": "Always applies on child completion signal" } ] }, "MULTI_INTENT_ROUTING_POLICY": { "description": "How master handles requests that contain tasks for multiple child agents.", "detection_rules": [ { "rule_id": "MIP-001", "name": "Score-based multi-intent detection", "condition": "top-1 and top-2 embedding scores both >= 0.58 AND different child targets AND score gap <= 0.06", "action": "Declare multi_intent. Identify primary (higher score) and secondary (lower score)." }, { "rule_id": "MIP-002", "name": "Explicit connector detection", "condition": "User message contains connector words ('and then', 'also', 'as well as', 'both', 'together') between two domain terms", "action": "Force multi-intent even if embedding scores don't both exceed threshold." } ], "resolution_order": [ "1. Apply dependency chain: if primary depends on secondary, reverse the order.", "2. Route to primary target immediately.", "3. QUEUE_SECONDARY_TASK for secondary target.", "4. Communicate both tasks to user in handoff message.", "5. After primary completes, auto-prompt for secondary unless user redirects." ], "dependency_chain_for_ordering": { "onboarding_before_template": "HARD", "onboarding_before_campaign": "HARD", "template_before_campaign": "HARD", "onboarding_before_chatbot": "SOFT", "template_before_chatbot": "CONDITIONAL" }, "examples": [ { "input": "Help me complete onboarding and then create a template", "primary": "Onboarding Helper", "secondary_queued": "Template Helper", "reason": "Onboarding is hard dependency for template" }, { "input": "Create a template and use it in campaign", "primary": "Template Helper", "secondary_queued": "Campaign Helper", "reason": "Template must be approved before campaign" }, { "input": "My bot is not replying and I also need a campaign", "primary": "Chatbot Helper", "secondary_queued": "Campaign Helper", "reason": "Bot troubleshoot is more urgent; both declared explicitly" }, { "input": "I want onboarding, chatbot, and campaign", "primary": "Onboarding Helper", "secondary_queued": ["Chatbot Helper", "Campaign Helper"], "reason": "Dependency order: onboarding first" } ] }, "ROUTING_PERFORMANCE_VALIDATION_PLAN": { "description": "Framework for measuring and validating intent-based routing quality in Master Agent.", "test_phases": [ { "phase": 1, "name": "Semantic Core Test", "description": "Pure semantic inputs with no domain keywords. Tests embedding engine only." }, { "phase": 2, "name": "Intent vs Keyword Collision", "description": "Inputs where keyword could mislead. Embedding must win." }, { "phase": 3, "name": "Contextual Short Reply", "description": "Short inputs during active child sessions. Tests sticky routing." }, { "phase": 4, "name": "Multi-intent Decomposition", "description": "Compound requests. Tests queue and handoff." }, { "phase": 5, "name": "Regression", "description": "Known past failure patterns. Must all pass." } ] }, "EMBEDDING_TRIGGER_TEST_CASES": [ { "test_id": "ET-001", "test_type": "PURE_SEMANTIC", "user_input": "Can I use my current number for this?", "active_context": null, "expected_primary_intent": "onboarding_eligibility", "expected_secondary_intents": ["onboarding_start"], "expected_target_agent": "Onboarding Helper", "expected_routing_reason": "Semantic: 'can I use my number' → eligibility/qualification check for WhatsApp API", "keyword_risk": "No explicit onboarding keywords present — pure embedding test", "pass_condition": "Routes to Onboarding Helper via onboarding_eligibility intent with score >= 0.62", "fail_condition": "Routes to wrong child OR falls to clarification despite clear semantic signal", "recommended_fix_if_failed": "Add 'can I use my current number' to onboarding_eligibility semantic_cluster_examples. Recompute centroid." }, { "test_id": "ET-002", "test_type": "PURE_SEMANTIC", "user_input": "How do I know if I qualify?", "active_context": null, "expected_primary_intent": "onboarding_eligibility", "expected_secondary_intents": [], "expected_target_agent": "Onboarding Helper", "expected_routing_reason": "'Qualify' = eligibility language. No domain keyword needed.", "keyword_risk": "No WABA/onboarding keyword. Pure embedding.", "pass_condition": "onboarding_eligibility scores >= 0.62. Routes to Onboarding Helper.", "fail_condition": "Falls to clarification or routes elsewhere.", "recommended_fix_if_failed": "Add 'how do I know if I qualify' to eligibility cluster." }, { "test_id": "ET-003", "test_type": "PURE_SEMANTIC", "user_input": "I need something for order update messages", "active_context": null, "expected_primary_intent": "template_start", "expected_secondary_intents": [], "expected_target_agent": "Template Helper", "expected_routing_reason": "'Order update messages' = transactional notification template use case. No 'template' keyword used.", "keyword_risk": "User never says 'template'. Pure semantic test.", "pass_condition": "template_start scores >= 0.62. Routes to Template Helper.", "fail_condition": "Routes to Campaign Helper (broadcast confusion) or falls to clarification.", "recommended_fix_if_failed": "Ensure 'appointment reminders', 'order update messages', 'notification format' are in template_start cluster." }, { "test_id": "ET-004", "test_type": "PURE_SEMANTIC", "user_input": "I want to send offers to many customers", "active_context": null, "expected_primary_intent": "campaign_start", "expected_secondary_intents": [], "expected_target_agent": "Campaign Helper", "expected_routing_reason": "'Send offers to many customers' = bulk broadcast campaign. No 'campaign' keyword.", "keyword_risk": "No explicit 'campaign' or 'broadcast' keyword.", "pass_condition": "campaign_start scores >= 0.62. Routes to Campaign Helper. Dependency check fires if onboarding not done.", "fail_condition": "Routes to Template Helper (offer template confusion) or Onboarding.", "recommended_fix_if_failed": "Strengthen 'send to many', 'bulk message', 'offers to customers' in campaign_start cluster." }, { "test_id": "ET-005", "test_type": "PURE_SEMANTIC", "user_input": "My bot stopped answering", "active_context": null, "expected_primary_intent": "chatbot_troubleshooting", "expected_secondary_intents": [], "expected_target_agent": "Chatbot Helper", "expected_routing_reason": "'Bot stopped answering' = chatbot failure state. No 'chatbot' keyword needed.", "keyword_risk": "Uses 'bot' but not 'chatbot'. Tests semantic generalization.", "pass_condition": "chatbot_troubleshooting scores >= 0.62. Routes to Chatbot Helper.", "fail_condition": "Routes to Campaign Helper or Onboarding.", "recommended_fix_if_failed": "Add 'bot stopped answering', 'bot went silent', 'stopped replying' to chatbot_troubleshooting cluster." }, { "test_id": "ET-006", "test_type": "PURE_SEMANTIC", "user_input": "Why is my broadcast stuck?", "active_context": null, "expected_primary_intent": "campaign_troubleshooting", "expected_secondary_intents": [], "expected_target_agent": "Campaign Helper", "expected_routing_reason": "'Broadcast stuck' = campaign delivery failure.", "keyword_risk": "Uses 'broadcast' but not 'campaign'. 'Stuck' is ambiguous.", "pass_condition": "campaign_troubleshooting scores >= 0.62. Routes to Campaign Helper.", "fail_condition": "Routes to chatbot_troubleshooting or falls to clarification.", "recommended_fix_if_failed": "Ensure 'broadcast stuck', 'broadcast not sending' in campaign_troubleshooting cluster." }, { "test_id": "ET-007", "test_type": "PURE_SEMANTIC", "user_input": "Which template category fits order updates?", "active_context": null, "expected_primary_intent": "template_start", "expected_secondary_intents": ["template_review"], "expected_target_agent": "Template Helper", "expected_routing_reason": "'Template category' + 'order updates' = template domain guidance.", "keyword_risk": "Uses 'template' but question is about category selection — must NOT go to Campaign Helper.", "pass_condition": "Template Helper receives intent. Category guidance provided.", "fail_condition": "Routes to Campaign Helper despite 'template' keyword (wrong context reading).", "recommended_fix_if_failed": "Ensure template_start cluster includes category selection phrases." }, { "test_id": "ET-008", "test_type": "PURE_SEMANTIC", "user_input": "I want to automate replies when customers ask about pricing", "active_context": null, "expected_primary_intent": "chatbot_start", "expected_secondary_intents": ["chatbot_trigger_setup"], "expected_target_agent": "Chatbot Helper", "expected_routing_reason": "'Automate replies when customers ask' = chatbot trigger + flow setup.", "keyword_risk": "No 'chatbot' keyword. 'Automate replies' must trigger chatbot domain.", "pass_condition": "chatbot_start scores >= 0.62. Routes to Chatbot Helper.", "fail_condition": "Routes to Campaign Helper (bulk messaging confusion).", "recommended_fix_if_failed": "Add 'automate replies', 'automatic response when customers ask' to chatbot_start cluster." }, { "test_id": "ET-009", "test_type": "PURE_SEMANTIC", "user_input": "Has my WhatsApp registration been approved yet?", "active_context": null, "expected_primary_intent": "onboarding_verification_status", "expected_secondary_intents": [], "expected_target_agent": "Onboarding Helper", "expected_routing_reason": "'Registration approved' = verification status check.", "keyword_risk": "No 'onboarding' keyword. 'Registration approved' must match verification intent.", "pass_condition": "onboarding_verification_status scores >= 0.62.", "fail_condition": "Routes to campaign_status (confused by 'status').", "recommended_fix_if_failed": "Add 'registration approved', 'account approved yet' to verification cluster." }, { "test_id": "ET-010", "test_type": "PURE_SEMANTIC", "user_input": "I want customers to tap a button and visit my website", "active_context": null, "expected_primary_intent": "template_button_help", "expected_secondary_intents": [], "expected_target_agent": "Template Helper", "expected_routing_reason": "'Tap a button to visit website' = URL button in message template.", "keyword_risk": "No 'template' or 'button' explicitly — pure semantic.", "pass_condition": "template_button_help scores >= 0.62.", "fail_condition": "Routes to chatbot_response_type_help (button confusion).", "recommended_fix_if_failed": "Add 'tap to visit website', 'button to open URL' to template_button_help cluster." } ], "INTENT_VS_KEYWORD_COMPARISON_CASES": [ { "test_id": "IK-001", "test_type": "INTENT_VS_KEYWORD_COLLISION", "user_input": "Use this template in my campaign", "active_context": "Campaign Helper ACTIVE", "expected_primary_intent": "campaign_continue", "expected_target_agent": "Campaign Helper", "expected_routing_reason": "P=80 conflict rule: 'template' in active Campaign context = template SELECTION for campaign. Embedding intent = campaign_continue. Keyword 'template' must NOT switch to Template Helper.", "keyword_risk": "HIGH — 'template' keyword would fire Template Helper rule if not overridden", "embedding_verdict": "campaign_continue wins due to context boost + P=80 rule", "keyword_verdict": "Would incorrectly fire template_start", "pass_condition": "Stays in Campaign Helper. Template is treated as campaign slot, not new template creation.", "fail_condition": "Switches to Template Helper", "recommended_fix_if_failed": "Ensure P=80 conflict rule fires before domain keyword rules. Active child context must override keyword." }, { "test_id": "IK-002", "test_type": "INTENT_VS_KEYWORD_COLLISION", "user_input": "keyword should be pricing", "active_context": "Chatbot Helper ACTIVE", "expected_primary_intent": "chatbot_trigger_setup", "expected_target_agent": "Chatbot Helper", "expected_routing_reason": "P=78 rule: 'keyword' in active Chatbot context = trigger keyword setup. Must NOT trigger generic routing keyword logic.", "keyword_risk": "HIGH — 'keyword' is used in routing engine logic itself", "embedding_verdict": "chatbot_trigger_setup wins due to active child context", "keyword_verdict": "Could incorrectly match generic routing", "pass_condition": "chatbot_trigger_setup intent recognized. 'pricing' treated as trigger word value.", "fail_condition": "Master routing breaks or routes to wrong child", "recommended_fix_if_failed": "P=78 conflict rule must prevent 'keyword' from escaping to generic handler when Chatbot is active." }, { "test_id": "IK-003", "test_type": "INTENT_VS_KEYWORD_COLLISION", "user_input": "manual", "active_context": "Onboarding Helper ACTIVE", "expected_primary_intent": "onboarding_manual_setup", "expected_target_agent": "Onboarding Helper", "expected_routing_reason": "Active child = Onboarding. 'manual' in onboarding context = manual setup mode. P=85 sticky routing applies.", "keyword_risk": "MEDIUM — 'manual' is ambiguous across domains", "embedding_verdict": "onboarding_manual_setup with context boost", "keyword_verdict": "Ambiguous — could match multiple rules", "pass_condition": "onboarding_manual_setup intent fires. Stays in Onboarding Helper.", "fail_condition": "Clarification triggered unnecessarily OR switches to Chatbot Helper", "recommended_fix_if_failed": "Active child sticky routing must resolve 'manual' without clarification when Onboarding is active." }, { "test_id": "IK-004", "test_type": "INTENT_VS_KEYWORD_COLLISION", "user_input": "publish it", "active_context": "Chatbot Helper ACTIVE", "expected_primary_intent": "chatbot_publish", "expected_target_agent": "Chatbot Helper", "expected_routing_reason": "P=75 rule: 'publish' in active Chatbot context = publish chatbot. Must NOT route to campaign send.", "keyword_risk": "MEDIUM — 'publish' could match template submission or campaign send", "embedding_verdict": "chatbot_publish + active child context boost wins", "keyword_verdict": "Could match Template Helper submission rule", "pass_condition": "chatbot_publish intent fires. Bot goes live.", "fail_condition": "Switches to Template Helper or Campaign Helper", "recommended_fix_if_failed": "P=75 conflict rule enforced. Active Chatbot context must prevent publish routing to other children." }, { "test_id": "IK-005", "test_type": "INTENT_VS_KEYWORD_COLLISION", "user_input": "I don't want to make a template, just run the campaign directly", "active_context": null, "expected_primary_intent": "campaign_start", "expected_target_agent": "Onboarding Helper", "expected_routing_reason": "Intent detected: campaign_start. But dependency check: template and onboarding required. RESOLVE_DEPENDENCY_FIRST → route to Onboarding Helper. Queue campaign.", "keyword_risk": "MEDIUM — 'template' and 'campaign' both present. Without context, keyword confusion risk.", "embedding_verdict": "campaign_start detected. Dependency block triggers.", "keyword_verdict": "Could confusingly route to Template Helper due to 'template' keyword", "pass_condition": "campaign_start identified. Dependency block fires. Onboarding Helper activated. Campaign queued.", "fail_condition": "Routes to Template Helper (wrong) or Campaign Helper without dependency check", "recommended_fix_if_failed": "Intent detection must run BEFORE dependency check. Dependency check fires on identified intent, not on keywords." }, { "test_id": "IK-006", "test_type": "INTENT_VS_KEYWORD_COLLISION", "user_input": "What is the status?", "active_context": "Campaign Helper ACTIVE", "expected_primary_intent": "campaign_status", "expected_target_agent": "Campaign Helper", "expected_routing_reason": "Active child = Campaign. 'Status' → campaign_status. Must not trigger onboarding_verification_status.", "keyword_risk": "HIGH — 'status' matches multiple intents across domains", "embedding_verdict": "campaign_status with active child boost wins", "keyword_verdict": "Ambiguous — 'status' keyword matches both campaign and onboarding domain rules", "pass_condition": "campaign_status fires. Campaign Helper handles status query.", "fail_condition": "Triggers clarification or routes to Onboarding Helper", "recommended_fix_if_failed": "Active child context must resolve 'status' ambiguity without clarification." } ], "REGRESSION_ROUTING_TEST_CASES": [ { "test_id": "RR-001", "test_type": "REGRESSION", "description": "Multi-slot: date + city extracted together in same onboarding utterance", "user_input": "Book my onboarding call for 25 March in Mumbai", "active_context": null, "expected_primary_intent": "onboarding_start", "expected_target_agent": "Onboarding Helper", "expected_extracted_params": { "date": "25 March", "city": "Mumbai" }, "previous_bad_behavior": "Only one slot (date or city) extracted; second slot was lost", "pass_condition": "Both date='25 March' AND city='Mumbai' extracted in same turn. No re-ask for already-provided slots.", "fail_condition": "Only one param extracted. Bot re-asks for already-provided param.", "recommended_fix_if_failed": "Entity extractor must iterate ALL param slots, not stop after first match." }, { "test_id": "RR-002", "test_type": "REGRESSION", "description": "Phone Number ID must not be classified as sys.phone", "user_input": "My Phone Number ID is 1203641234567", "active_context": "Onboarding Helper ACTIVE", "expected_primary_intent": "onboarding_continue", "expected_target_agent": "Onboarding Helper", "expected_extracted_params": { "phone_number_id": "1203641234567" }, "previous_bad_behavior": "Long numeric string was extracted as sys.phone, wrong slot filled", "pass_condition": "phone_number_id slot filled. sys.phone slot NOT touched.", "fail_condition": "1203641234567 extracted into sys.phone slot", "recommended_fix_if_failed": "phone_number_id entity must be distinct from sys.phone. Slot definition in intent must specify phone_number_id as entity type." }, { "test_id": "RR-003", "test_type": "REGRESSION", "description": "Template mention in active campaign MUST NOT switch to Template Helper", "user_input": "I am not sure which template to use", "active_context": "Campaign Helper ACTIVE", "expected_primary_intent": "campaign_continue", "expected_target_agent": "Campaign Helper", "previous_bad_behavior": "Template keyword caused switch to Template Helper mid-campaign, destroying campaign slot context", "pass_condition": "Stays in Campaign Helper. P=80 conflict rule enforced.", "fail_condition": "Switches to Template Helper", "recommended_fix_if_failed": "Verify P=80 MasterRouteRule is in DB. Verify active_child_agent check fires before domain keyword routing." }, { "test_id": "RR-004", "test_type": "REGRESSION", "description": "Short reply 'Evening' during active onboarding slot-fill must stay in Onboarding", "user_input": "Evening", "active_context": "Onboarding Helper ACTIVE, expected_next_action: awaiting_preferred_time", "expected_primary_intent": "provide_slot_value", "expected_target_agent": "Onboarding Helper", "previous_bad_behavior": "Single word 'Evening' caused re-routing or clarification instead of being treated as slot response", "pass_condition": "Forwarded to Onboarding Helper as preferred_time='Evening' slot fill. No clarification.", "fail_condition": "Clarification triggered or different child activated", "recommended_fix_if_failed": "expected_next_action context takes highest priority. All inputs treated as slot responses when awaiting slot." }, { "test_id": "RR-005", "test_type": "REGRESSION", "description": "is me eligible to use waba? mid-onboarding → ask_eligibility_mid_flow NOT check_eligibility", "user_input": "is me eligible to use waba?", "active_context": "onboarding-active context present, lifespan=19", "expected_primary_intent": "ask_eligibility_mid_flow", "expected_target_agent": "Onboarding Helper", "previous_bad_behavior": "Global check_eligibility matched at 52% confidence, overriding context-gated ask_eligibility_mid_flow. User got pre-onboarding eligibility checklist instead of reassurance.", "pass_condition": "ask_eligibility_mid_flow intent fires (context-gated, gets +0.12 boost). User reassured they are already in onboarding = eligible.", "fail_condition": "check_eligibility (global) wins the match", "recommended_fix_if_failed": "Verify ask_eligibility_mid_flow exists in seedWhatsAppOnboardingHelper.js with inputContexts: ['onboarding-active']. Context boost must be applied in intentMatcher.service.js." }, { "test_id": "RR-006", "test_type": "REGRESSION", "description": "Campaign created without onboarding — dependency block must fire", "user_input": "I want to create a campaign right now", "active_context": "Fresh session. No onboarding completed.", "expected_primary_intent": "campaign_start", "expected_target_agent": "Onboarding Helper", "previous_bad_behavior": "Master routed directly to Campaign Helper without dependency check", "pass_condition": "campaign_start intent detected. Dependency block fires. Routes to Onboarding Helper. Campaign queued.", "fail_condition": "Campaign Helper activated without onboarding dependency check", "recommended_fix_if_failed": "Dependency check must run on detected intent, not just on keywords." }, { "test_id": "RR-007", "test_type": "REGRESSION", "description": "Sticky agent cleared after task completion — no ghost routing", "user_input": "Now create a message template", "active_context": "Onboarding Helper just completed (status=COMPLETED). active_child_agent cleared.", "expected_primary_intent": "template_start", "expected_target_agent": "Template Helper", "previous_bad_behavior": "active_child_agent stayed as Onboarding Helper after completion; new request incorrectly routed back to Onboarding", "pass_condition": "Template Helper receives routing. Onboarding Helper status = COMPLETED, NOT active.", "fail_condition": "Routes back to Onboarding Helper", "recommended_fix_if_failed": "Orchestrator must set active_child_agent=null on COMPLETED event before processing next input." }, { "test_id": "RR-008", "test_type": "REGRESSION", "description": "Chatbot before onboarding = SOFT block (warning only, not hard block)", "user_input": "I want to build a chatbot", "active_context": "Fresh session. No onboarding.", "expected_primary_intent": "chatbot_start", "expected_target_agent": "Chatbot Helper", "previous_bad_behavior": "Master hard-blocked chatbot (same as campaign block) even though chatbot dependency is SOFT", "pass_condition": "Routes to Chatbot Helper WITH a warning about onboarding recommendation. NOT blocked.", "fail_condition": "Chatbot Helper blocked and user sent to Onboarding Helper", "recommended_fix_if_failed": "Dependency policy must distinguish HARD (campaign) from SOFT (chatbot). Chatbot should warn, not block." } ], "ACCEPTANCE_THRESHOLDS": { "description": "Measurable pass/fail benchmarks for intent-based routing quality.", "metrics": [ { "metric_id": "AT-001", "name": "Top-1 Routing Accuracy — Core Flows", "definition": "Percentage of inputs where the correct child agent is selected on first attempt", "target": ">= 90%", "measurement": "Run all EMBEDDING_TRIGGER_TEST_CASES. Count correct top-1 routings / total." }, { "metric_id": "AT-002", "name": "Top-2 Recovery Accuracy", "definition": "Percentage of inputs where correct child appears in top-2 intents even if top-1 is wrong", "target": ">= 96%", "measurement": "If top-1 is wrong, check if correct intent is in top-2. Count recoverable / total." }, { "metric_id": "AT-003", "name": "Active-Context Short Reply Accuracy", "definition": "Percentage of short contextual replies (1–3 words) that correctly stay with active child", "target": ">= 95%", "measurement": "Run all contextual short reply tests. Count correct sticky routings / total." }, { "metric_id": "AT-004", "name": "Wrong Child Handoff Rate", "definition": "Percentage of turns where user is sent to wrong child agent", "target": "<= 5%", "measurement": "Count wrong-child handoffs / total routed turns across all test cases." }, { "metric_id": "AT-005", "name": "False Keyword Override Rate", "definition": "Percentage of cases where keyword routing overrides a stronger embedding signal", "target": "<= 3%", "measurement": "Run INTENT_VS_KEYWORD_COMPARISON_CASES. Count keyword wins when embedding was correct / total." }, { "metric_id": "AT-006", "name": "Multi-Intent Decomposition Accuracy", "definition": "Percentage of multi-intent inputs where both primary and secondary tasks are correctly identified and queued", "target": ">= 85%", "measurement": "Run all multi-intent test cases. Primary correct + secondary queued = pass." }, { "metric_id": "AT-007", "name": "Regression Pass Rate", "definition": "All previously identified failure patterns must pass — zero tolerance", "target": "100%", "measurement": "Run all REGRESSION_ROUTING_TEST_CASES. Any fail = regression blocker." }, { "metric_id": "AT-008", "name": "Fallback Correctness Rate", "definition": "Percentage of low-confidence inputs that correctly fall to clarification rather than wrong routing", "target": ">= 90%", "measurement": "Run adversarial/ambiguous inputs. Count correct clarification triggers / total ambiguous inputs." }, { "metric_id": "AT-009", "name": "System Stability — No 500 Errors", "definition": "100% of inputs must return HTTP 200, regardless of content", "target": "100%", "measurement": "Run gibberish, emoji, URL, bare number inputs. Zero 500s expected." } ], "threshold_table": { "top_1_accuracy": { "target": ">=90%", "critical": true }, "top_2_recovery": { "target": ">=96%", "critical": false }, "context_short_reply": { "target": ">=95%", "critical": true }, "wrong_child_rate": { "target": "<=5%", "critical": true }, "keyword_override_rate":{ "target": "<=3%", "critical": false }, "multi_intent_accuracy":{ "target": ">=85%", "critical": false }, "regression_pass_rate": { "target": "100%", "critical": true }, "fallback_correctness": { "target": ">=90%", "critical": false }, "system_stability": { "target": "100%", "critical": true } } }, "IMPROVEMENT_RECOMMENDATION_FRAMEWORK": { "description": "Loop for continuously improving intent routing quality after test runs.", "improvement_loop": [ { "step": 1, "name": "Run Test Suite", "action": "Execute all 5 test phases. Record actual top-1 intent, actual target agent, and actual score for each test case." }, { "step": 2, "name": "Score Against Thresholds", "action": "Compare actual results against ACCEPTANCE_THRESHOLDS. Identify which metrics fall below target." }, { "step": 3, "name": "Failure Category Assignment", "action": "Map each failure to a FAILURE_DIAGNOSIS category (FD-001 to FD-006 in part3.json)." }, { "step": 4, "name": "Centroid Expansion", "action": "For semantic test failures: add the failing input as a new positive_example in the correct intent's semantic_cluster_examples. Recompute centroid.", "trigger": "test_type=PURE_SEMANTIC fails" }, { "step": 5, "name": "Conflict Rule Audit", "action": "For keyword collision failures: verify P=75/78/80 MasterRouteRules exist in DB with correct condition logic. Re-seed if missing.", "trigger": "test_type=INTENT_VS_KEYWORD_COLLISION fails" }, { "step": 6, "name": "Dependency Policy Update", "action": "For dependency failures: update dependency_chain_for_ordering and verify orchestrationExecutor.service.js applies correct HARD vs SOFT policy.", "trigger": "Dependency-related test failures" }, { "step": 7, "name": "Regression Blocker Resolution", "action": "Any Category H or RR-xxx regression failure is a BLOCKER. Must be fixed before deployment.", "trigger": "Any regression test fails" }, { "step": 8, "name": "Re-run and Verify", "action": "After fixes, re-run the specific failed test cases plus full regression suite. Confirm no regressions introduced." } ], "centroid_update_command": "routingEngine.recomputeIntentCentroids(intentId) — call after updating semantic_cluster_examples", "recommended_test_cadence": "Run full suite: on every seed script change, on every routing rule change, before every deployment", "regression_test_cadence": "Run Category H + RR-xxx on every pull request" } }