@ema.co/mcp-toolkit 1.6.0 → 1.7.1

package/dist/sdk/intent-architect.js

@@ -0,0 +1,883 @@
+/**
+ * Intent Architect - LLM-driven intent decomposition
+ *
+ * This module provides the prompt and types for decomposing user requests
+ * into structured IntentSpecs using the Intent Architect approach.
+ *
+ * KEY PRINCIPLE: Intent Architect focuses on WHY + WHAT + CONSTRAINTS
+ * It does NOT focus on HOW (mechanisms) - that's the Solver's job.
+ *
+ * - WHY: Business outcome, success metrics, risks
+ * - WHAT: Deliverables, decisions, required evidence
+ * - CONSTRAINTS: Hard requirements that limit solution space
+ * - HOW: Deferred to Solver (which nodes, which channels)
+ *
+ * ## Progressive Enhancement (Additive, not Big Bang)
+ *
+ * Use `selectIntentStrategy()` to determine the appropriate level:
+ *
+ * 1. **SIMPLE**: Basic prompt, no qualification needed
+ *    - Clear goal, known channel, no approvals, no taxonomy
+ *    - Fast, cheap, skip Intent Architect
+ *
+ * 2. **MODERATE**: Some qualification needed
+ *    - Has approvals OR has taxonomy OR multiple intents
+ *    - Use Intent Architect to ask Gate 1-2 questions
+ *
+ * 3. **COMPLEX**: Full Intent Architect
+ *    - Custom approvals, taxonomy, multi-step decisions
+ *    - All 5 gates, full IntentSpec
+ *
+ * This allows gradual adoption - start simple, escalate as needed.
+ */
+import * as fs from "fs";
+import * as path from "path";
+/** Cached gate definitions loaded from config */
+let cachedGateConfig = null;
+/**
+ * Load gate definitions from config file.
+ *
+ * Config is loaded from resources/config/gates.json and cached.
+ * Falls back to embedded defaults if config file is not found.
+ *
+ * @param forceReload - If true, reloads even if cached
+ */
+export function loadGateConfig(forceReload = false) {
+    if (cachedGateConfig && !forceReload) {
+        return cachedGateConfig;
+    }
+    // Try multiple paths (works in both src and dist)
+    const possiblePaths = [
+        path.resolve(__dirname, "../../resources/config/gates.json"),
+        path.resolve(__dirname, "../../../resources/config/gates.json"),
+        path.resolve(process.cwd(), "resources/config/gates.json"),
+    ];
+    for (const configPath of possiblePaths) {
+        if (fs.existsSync(configPath)) {
+            try {
+                const content = fs.readFileSync(configPath, "utf-8");
+                const config = JSON.parse(content);
+                // Basic validation
+                if (!config.version || !Array.isArray(config.gates) || config.gates.length === 0) {
+                    throw new Error("Invalid gate config: missing version or gates array");
+                }
+                // Validate each gate has required fields
+                for (const gate of config.gates) {
+                    if (!gate.id || !gate.name || !gate.type || !gate.enforcement) {
+                        throw new Error(`Invalid gate ${gate.id}: missing required fields`);
+                    }
+                }
+                cachedGateConfig = config;
+                return config;
+            }
+            catch (err) {
+                throw new Error(`Failed to load gate config from ${configPath}: ${err}`);
+            }
+        }
+    }
+    // Fallback to embedded defaults (emergency only)
+    console.warn("Gate config not found, using embedded defaults");
+    cachedGateConfig = getDefaultGateConfig();
+    return cachedGateConfig;
+}
+/** Embedded defaults - only used if config file not found */
+function getDefaultGateConfig() {
+    return {
+        version: "1.0.0-fallback",
+        owner: "embedded",
+        gates: [
+            { id: 1, name: "Modality + Trigger + Consent", type: "blocking", enforcement: "required", base_weight: 0.6, asks: ["voice vs email vs chat", "inbound/outbound", "consent requirements"], blockers: ["channel_ambiguity", "consent_unknown"], triggers: ["voice", "call", "phone", "outbound", "inbound"], default_value: null },
+            { id: 2, name: "Outcome + Qualification Definition", type: "blocking", enforcement: "required", base_weight: 0.6, asks: ["what 'qualified' means", "disqualifiers"], blockers: ["qualification_definition_missing", "outcome_unclear"], triggers: ["qualify", "qualified", "fit", "assess"], default_value: null },
+            { id: 3, name: "Use-case Taxonomy + Content Scoping", type: "discovery", enforcement: "recommended", base_weight: 0.4, asks: ["taxonomy source", "KB sources"], blockers: ["taxonomy_unknown"], triggers: ["use-case", "category", "classify"], default_value: "general_category" },
+            { id: 4, name: "Governance / HITL Semantics", type: "blocking", enforcement: "required", base_weight: 0.6, asks: ["who approves", "SLA", "fallback"], blockers: ["approver_unknown", "approval_semantics_unclear"], triggers: ["approval", "review", "hitl", "human"], default_value: null },
+            { id: 5, name: "Integrations + Systems of Record", type: "informational", enforcement: "optional", base_weight: 0.2, asks: ["CRM", "email", "telephony"], blockers: ["integration_requirements_unknown"], triggers: ["salesforce", "crm", "hubspot"], default_value: "none" },
+        ],
+    };
+}
+/**
+ * Get gate definitions as a record (for backward compatibility).
+ * Loads from config file.
+ */
+export function getGateDefinitions() {
+    const config = loadGateConfig();
+    const result = {};
+    for (const gate of config.gates) {
+        result[gate.id] = {
+            id: gate.id,
+            name: gate.name,
+            type: gate.type,
+            enforcement: gate.enforcement,
+            asks: gate.asks,
+            blockers: gate.blockers,
+            triggers: gate.triggers,
+            default_value: gate.default_value ?? undefined,
+        };
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Prompt Loading
+// ─────────────────────────────────────────────────────────────────────────────
+let _cachedPrompt = null;
+/**
+ * Load the Intent Architect prompt from the markdown file
+ */
+export function getIntentArchitectPrompt() {
+    if (_cachedPrompt)
+        return _cachedPrompt;
+    const promptPath = path.join(__dirname, "../prompts/intent-architect.md");
+    try {
+        _cachedPrompt = fs.readFileSync(promptPath, "utf-8");
+        return _cachedPrompt;
+    }
+    catch (e) {
+        // Fallback: return embedded prompt summary
+        console.warn("[IntentArchitect] Could not load prompt file, using embedded fallback");
+        return EMBEDDED_PROMPT_SUMMARY;
+    }
+}
+// Embedded fallback in case file isn't available (e.g., in bundled contexts)
+const EMBEDDED_PROMPT_SUMMARY = `You are "Intent Architect", an expert at turning vague user requests into a precise, testable IntentSpec.
+
+Your job is NOT to immediately generate a workflow. Your job is to:
+1) Extract and refine intent (WHY → WHAT → HOW)
+2) Identify missing qualification details
+3) Ask minimal high-information questions
+4) Produce a structured IntentSpec
+5) Map to candidate graph skeleton only after critical unknowns resolved
+
+Key principles:
+- WHY = business outcome + success metrics + risks
+- WHAT = deliverables + decisions + required evidence
+- HOW = channel + policies + constraints + integrations + approvals
+- Never use platform jargon without translating
+- Make "use-case identification" explicit and concrete
+
+Output format: A) Intent Hypothesis, B) IntentSpec (YAML), C) Qualification Questions, D) Candidate Graph, E) Convergence Plan`;
+/**
+ * Generate the user prompt for a specific request
+ */
+export function generateIntentArchitectUserPrompt(userRequest, context) {
+    let prompt = `## User Request\n\n"${userRequest}"\n\n`;
+    if (context) {
+        prompt += `## Known Context\n\n`;
+        if (context.persona_type) {
+            prompt += `- Interaction type: ${context.persona_type.toUpperCase()} (${context.persona_type === "voice" ? "phone/call" :
+                context.persona_type === "chat" ? "text-based chat" : "dashboard/async"})\n`;
+        }
+        if (context.available_integrations?.length) {
+            prompt += `- Available integrations: ${context.available_integrations.join(", ")}\n`;
+        }
+        if (context.existing_answers && Object.keys(context.existing_answers).length > 0) {
+            prompt += `\n### Previously Answered Questions\n`;
+            for (const [q, a] of Object.entries(context.existing_answers)) {
+                prompt += `- ${q}: ${a}\n`;
+            }
+        }
+        prompt += "\n";
+    }
+    if (context?.action_catalog) {
+        prompt += `## Available Actions (for graph generation)\n\n${context.action_catalog}\n\n`;
+    }
+    prompt += `## Task
+
+Analyze this request and produce sections A–E as specified in your instructions.
+
+Focus on:
+1. Understanding the real business goal (WHY), not just the stated mechanism
+2. Identifying ALL decisions that need to be made and their required evidence
+3. Making "use-case identification" concrete if mentioned
+4. Specifying exactly who approves what, where, and with what SLA
+5. Asking minimal, high-information questions tied to specific IntentSpec fields
+
+Return your response in the structured format (A through E).`;
+    return prompt;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Response Parsing
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Parse the LLM response to extract structured data
+ * Note: This is best-effort - the LLM output is semi-structured
+ */
+export function parseIntentArchitectResponse(response) {
+    const result = {};
+    // Try to extract YAML from section B
+    const yamlMatch = response.match(/```yaml\s*([\s\S]*?)\s*```/);
+    if (yamlMatch) {
+        try {
+            // Note: In production, use a proper YAML parser
+            // For now, just extract it for reference
+            result.intent_spec = { _raw_yaml: yamlMatch[1] };
+        }
+        catch (e) {
+            console.warn("[IntentArchitect] Could not parse YAML:", e);
+        }
+    }
+    // Extract qualification questions
+    const questions = [];
+    const questionPattern = /\*\*Q(\d+)\*\*[:\s]*\*\*([^*]+)\*\*|Q(\d+)[:\s]+([^\n]+)/g;
+    let match;
+    while ((match = questionPattern.exec(response)) !== null) {
+        const id = match[1] || match[3];
+        const question = (match[2] || match[4])?.trim();
+        if (id && question) {
+            questions.push({
+                id: `Q${id}`,
+                question,
+                tied_to_field: "", // Would need more sophisticated parsing
+                category: "WHAT", // Default
+            });
+        }
+    }
+    if (questions.length > 0) {
+        result.qualification_questions = questions;
+    }
+    // Check for deferred graph
+    if (response.toLowerCase().includes("deferred") || response.toLowerCase().includes("blocking")) {
+        result.candidate_graph = {
+            status: "deferred",
+            deferred_reason: "Critical unknowns must be resolved first",
+        };
+    }
+    return result;
+}
+/**
+ * Get the complete prompt package for Intent Architect
+ */
+export function getIntentArchitectPromptPackage(userRequest, context) {
+    return {
+        system: getIntentArchitectPrompt(),
+        user: generateIntentArchitectUserPrompt(userRequest, context),
+    };
+}
+/**
+ * Convert ComplexityAssessment to legacy IntentComplexity enum.
+ */
+export function complexityAssessmentToEnum(assessment) {
+    if (assessment.level < 0.34)
+        return "simple";
+    if (assessment.level < 0.67)
+        return "moderate";
+    return "complex";
+}
+/**
+ * Convert legacy IntentComplexity enum to a ComplexityAssessment.
+ */
+export function enumToComplexityAssessment(complexity, rationale = "Converted from legacy enum") {
+    const levelMap = {
+        simple: 0.2,
+        moderate: 0.5,
+        complex: 0.8,
+    };
+    return {
+        level: levelMap[complexity],
+        confidence: {
+            kind: "confidence",
+            value: 0.7, // Medium confidence for enum-based detection
+            scale: "0_1",
+            rationale: "Converted from legacy enum",
+        },
+        signals: [],
+        blockers: [],
+        rationale,
+    };
+}
+/**
+ * Gate definitions loaded from config.
+ *
+ * @deprecated Use getGateDefinitions() instead - this is kept for backward compatibility.
+ * Gate definitions are now loaded from resources/config/gates.json
+ */
+export const GATE_DEFINITIONS = (() => {
+    // Lazy initialization from config
+    try {
+        return getGateDefinitions();
+    }
+    catch {
+        // Return minimal fallback if config loading fails at module load time
+        return {
+            1: { id: 1, name: "Modality", type: "blocking", enforcement: "required", asks: [], blockers: [], triggers: [] },
+            2: { id: 2, name: "Qualification", type: "blocking", enforcement: "required", asks: [], blockers: [], triggers: [] },
+            3: { id: 3, name: "Taxonomy", type: "discovery", enforcement: "recommended", asks: [], blockers: [], triggers: [] },
+            4: { id: 4, name: "Governance", type: "blocking", enforcement: "required", asks: [], blockers: [], triggers: [] },
+            5: { id: 5, name: "Integrations", type: "informational", enforcement: "optional", asks: [], blockers: [], triggers: [] },
+        };
+    }
+})();
+/**
+ * Default base weights by enforcement level.
+ * These are used if a gate doesn't specify a base_weight in config.
+ */
+const DEFAULT_BASE_WEIGHTS = {
+    required: 0.6,
+    recommended: 0.4,
+    optional: 0.2,
+};
+/**
+ * Compute weights for a gate based on input and context.
+ *
+ * Uses gate config from resources/config/gates.json for:
+ * - base_weight (or defaults based on enforcement level)
+ * - triggers (signals that boost weight)
+ */
+export function computeGateWeights(gateId, input, context) {
+    const config = loadGateConfig();
+    const gateConfig = config.gates.find(g => g.id === gateId);
+    const gate = getGateDefinitions()[gateId];
+    if (!gate)
+        return { base: 0, signal_boost: 0, context_multiplier: 1, final_score: 0 };
+    const inputLower = input.toLowerCase();
+    // Base weight from config (or default based on enforcement)
+    const base = gateConfig?.base_weight ?? DEFAULT_BASE_WEIGHTS[gate.enforcement];
+    // Signal boost: count triggers found, normalize to 0-1
+    const triggersFound = gate.triggers.filter(t => inputLower.includes(t.toLowerCase()));
+    const signal_boost = Math.min(1.0, triggersFound.length * 0.2);
+    // Context multiplier
+    let context_multiplier = 1.0;
+    if (context) {
+        // Voice personas boost Gate 1 (modality)
+        if (context.persona_type === "voice" && gateId === 1) {
+            context_multiplier *= 1.5;
+        }
+        // Compliance mode boosts Gate 4 (governance)
+        if (context.compliance_mode && gateId === 4) {
+            context_multiplier *= 2.0;
+        }
+        // Outbound mode boosts Gate 1 (consent)
+        if (context.outbound_mode && gateId === 1) {
+            context_multiplier *= 1.5;
+        }
+        // Custom multipliers
+        if (context.custom_multipliers?.[gateId]) {
+            context_multiplier *= context.custom_multipliers[gateId];
+        }
+    }
+    // Final score
+    const final_score = base * (1 + signal_boost) * context_multiplier;
+    return { base, signal_boost, context_multiplier, final_score };
+}
+/**
+ * Get gates with computed weights, sorted by final score.
+ * Loads gate definitions from config.
+ */
+export function getGatesWithWeights(input, context) {
+    const gates = getGateDefinitions();
+    return Object.values(gates)
+        .map(gate => ({
+        ...gate,
+        weights: computeGateWeights(gate.id, input, context),
+    }))
+        .sort((a, b) => b.weights.final_score - a.weights.final_score);
+}
+/**
+ * Get gates that should be asked (score > threshold)
+ */
+export function getRequiredGates(input, context, threshold = 0.5) {
+    return getGatesWithWeights(input, context)
+        .filter(gate => gate.weights.final_score >= threshold || gate.type === "blocking");
+}
+/**
+ * Get discovery questions - gates where score is moderate (uncertain)
+ * These trigger more exploration rather than blocking
+ */
+export function getDiscoveryGates(input, context, uncertaintyRange = { min: 0.3, max: 0.7 }) {
+    return getGatesWithWeights(input, context)
+        .filter(gate => gate.type === "discovery" &&
+        gate.weights.final_score >= uncertaintyRange.min &&
+        gate.weights.final_score <= uncertaintyRange.max);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// LLM-DRIVEN DETECTION (Primary)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Prompt for LLM-based intent signal detection.
+ *
+ * The caller should send this to their LLM and parse the response
+ * using parseComplexitySignalsFromLLM().
+ */
+export function getComplexityDetectionPrompt(input) {
+    return {
+        system: `You are an intent classifier. Analyze the user request and detect INTENT signals (WHY/WHAT), NOT mechanisms (HOW).
+
+INTENT signals to detect:
+- governance: needs human approval, review, oversight, sign-off
+- decision: needs classification, categorization, routing, triage
+- qualification: needs evaluation, assessment, scoring, validation
+- multi_step: multiple sequential actions, outcomes
+- conditional: branching logic, different paths based on conditions
+- extraction: capture structured data, collect information
+
+DO NOT detect mechanisms (these are HOW, not WHY/WHAT):
+- "email" → mechanism, not intent
+- "Salesforce" → mechanism, not intent
+- "Slack" → mechanism, not intent
+
+Return JSON only:
+{
+  "governance": true/false,
+  "decision": true/false,
+  "qualification": true/false,
+  "multi_step": true/false,
+  "conditional": true/false,
+  "extraction": true/false,
+  "reasoning": "brief explanation"
+}`,
+        user: `Analyze this request for INTENT signals:\n\n"${input}"`,
+    };
+}
+/**
+ * Parse LLM response for complexity signals.
+ */
+export function parseComplexitySignalsFromLLM(llmResponse) {
+    try {
+        // Try to extract JSON from response
+        const jsonMatch = llmResponse.match(/\{[\s\S]*\}/);
+        if (!jsonMatch)
+            return null;
+        const parsed = JSON.parse(jsonMatch[0]);
+        const signals = {
+            has_governance_requirement: parsed.governance === true,
+            has_decision_requirement: parsed.decision === true,
+            has_qualification_requirement: parsed.qualification === true,
+            has_multi_step: parsed.multi_step === true,
+            has_conditional_logic: parsed.conditional === true,
+            has_extraction_requirement: parsed.extraction === true,
+            complexity: "simple",
+            reason: parsed.reasoning || "",
+            required_gates: [],
+            blockers: [],
+            safe_defaults: {},
+            unsafe_defaults: [],
+            detection_method: "llm",
+        };
+        // Compute complexity from signals
+        computeComplexityFromSignals(signals);
+        return signals;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute complexity level from detected signals.
+ * Populates: complexity, reason, required_gates, blockers, safe_defaults, unsafe_defaults
+ */
+function computeComplexityFromSignals(signals) {
+    // Compute individual signal weights (using TypedScore)
+    // Weights are calibrated so that:
+    // - Any single high-priority signal (governance, decision, qualification) → moderate (0.4+)
+    // - Two or more high-priority signals → complex (0.7+)
+    const signalScores = [];
+    if (signals.has_governance_requirement) {
+        signalScores.push({ kind: "weight", value: 0.4, scale: "0_1", rationale: "governance requirement detected" });
+    }
+    if (signals.has_decision_requirement) {
+        signalScores.push({ kind: "weight", value: 0.4, scale: "0_1", rationale: "decision/classification requirement detected" });
+    }
+    if (signals.has_qualification_requirement) {
+        signalScores.push({ kind: "weight", value: 0.35, scale: "0_1", rationale: "qualification requirement detected" });
+    }
+    if (signals.has_multi_step) {
+        signalScores.push({ kind: "weight", value: 0.2, scale: "0_1", rationale: "multi-step flow detected" });
+    }
+    if (signals.has_conditional_logic) {
+        signalScores.push({ kind: "weight", value: 0.2, scale: "0_1", rationale: "conditional logic detected" });
+    }
+    if (signals.has_extraction_requirement) {
+        signalScores.push({ kind: "weight", value: 0.15, scale: "0_1", rationale: "data extraction requirement detected" });
+    }
+    // Compute continuous complexity level (0-1)
+    const totalWeight = signalScores.reduce((sum, s) => sum + s.value, 0);
+    const complexityLevel = Math.min(1.0, totalWeight); // Cap at 1.0
+    // Initialize arrays
+    signals.blockers = [];
+    signals.safe_defaults = {};
+    signals.unsafe_defaults = [];
+    signals.required_gates = [];
+    // Determine blockers based on detected signals
+    if (signals.has_governance_requirement) {
+        signals.blockers.push("approver_unknown", "approval_semantics_unclear");
+        signals.unsafe_defaults.push("who approves", "approval channel", "SLA");
+        signals.required_gates.push(4);
+    }
+    if (signals.has_decision_requirement) {
+        signals.blockers.push("taxonomy_unknown", "classification_criteria_unclear");
+        signals.unsafe_defaults.push("use-case categories", "taxonomy source/owner");
+        signals.required_gates.push(3);
+    }
+    if (signals.has_qualification_requirement) {
+        signals.blockers.push("qualification_definition_missing");
+        signals.unsafe_defaults.push("qualification rubric", "what 'fit' means");
+        signals.required_gates.push(2);
+    }
+    if (signals.has_multi_step || signals.has_conditional_logic) {
+        // Multi-step usually needs outcome definition
+        if (!signals.required_gates.includes(2))
+            signals.required_gates.push(2);
+    }
+    // Safe defaults (can be assumed without asking)
+    signals.safe_defaults = {
+        "tone": "professional",
+        "retry_policy": "none",
+        "page_size": "10",
+    };
+    // Determine complexity level (legacy enum + new continuous score)
+    // Thresholds: simple < 0.34, moderate 0.34-0.66, complex >= 0.67
+    if (complexityLevel >= 0.67 ||
+        (signals.has_governance_requirement && signals.has_decision_requirement) ||
+        (signals.has_governance_requirement && signals.has_qualification_requirement)) {
+        signals.complexity = "complex";
+        if (!signals.reason) {
+            signals.reason = `High uncertainty: ${signals.blockers.length} blockers require resolution`;
+        }
+        // Complex = all gates
+        signals.required_gates = [1, 2, 3, 4, 5];
+    }
+    else if (complexityLevel >= 0.34) {
+        signals.complexity = "moderate";
+        if (!signals.reason) {
+            signals.reason = `Moderate uncertainty: ${signals.blockers.length} blockers on specific requirements`;
+        }
+        // Add Gate 1 (modality) if not already included
+        if (!signals.required_gates.includes(1))
+            signals.required_gates.unshift(1);
+        // Sort gates
+        signals.required_gates.sort((a, b) => a - b);
+    }
+    else {
+        signals.complexity = "simple";
+        if (!signals.reason)
+            signals.reason = "Low uncertainty - basic workflow generation sufficient";
+        signals.required_gates = [];
+        signals.blockers = [];
+        signals.unsafe_defaults = [];
+    }
+    // Backward compatibility
+    signals.recommended_gates = signals.required_gates;
+    // Populate typed assessment (new preferred structure)
+    const confidenceValue = signals.detection_method === "llm" ? 0.85 : 0.6;
+    signals.assessment = {
+        level: complexityLevel,
+        confidence: {
+            kind: "confidence",
+            value: confidenceValue,
+            scale: "0_1",
+            rationale: signals.detection_method === "llm"
+                ? "LLM-based detection with semantic understanding"
+                : "Regex-based fallback with limited semantic understanding",
+        },
+        signals: signalScores,
+        blockers: signals.blockers,
+        rationale: signals.reason,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// REGEX FALLBACK (Offline / Emergency)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Regex-based fallback for intent signal detection.
+ *
+ * ⚠️ This is a FALLBACK for when LLM is unavailable.
+ * Prefer using getComplexityDetectionPrompt() + parseComplexitySignalsFromLLM().
+ *
+ * Limitations:
+ * - Doesn't understand context or semantics
+ * - Can't handle synonyms or variations
+ * - May miss subtle intent signals
+ */
+export function analyzeComplexityFallback(input) {
+    const signals = {
+        has_governance_requirement: /\b(approval|approve|review|hitl|human\s+(review|approval|oversight)|sign.?off|authoriz|permission|consent|oversight)\b/i.test(input),
+        has_decision_requirement: /\b(use.?case|category|categories|categorize|classify|classification|route|routing|determine|decide|triage|segment|bucket)\b/i.test(input),
+        has_multi_step: /\b(and then|after that|next step|follow.?up|subsequently|finally)\b/i.test(input) ||
+            (input.split(/\band\b/i).length > 2 && input.length > 60),
+        has_conditional_logic: /\b(if|when|depending|based on|conditional|branch|otherwise|either.*or)\b/i.test(input),
+        has_extraction_requirement: /\b(capture|extract|collect|gather|record|log|document|note)\b/i.test(input),
+        has_qualification_requirement: /\b(qualify|qualifies|qualifying|qualification|evaluate|evaluates|assess|assessment|score|scoring|validate|verify|check if|determine if|eligible)\b/i.test(input),
+        complexity: "simple",
+        reason: "",
+        required_gates: [],
+        blockers: [],
+        safe_defaults: {},
+        unsafe_defaults: [],
+        detection_method: "regex_fallback",
+    };
+    computeComplexityFromSignals(signals);
+    return signals;
+}
+/**
+ * Analyze complexity - uses regex fallback by default.
+ *
+ * For LLM-driven detection (recommended), use:
+ * 1. getComplexityDetectionPrompt(input) → send to LLM
+ * 2. parseComplexitySignalsFromLLM(response) → get signals
+ *
+ * This function is for backward compatibility and offline scenarios.
+ */
+export function analyzeComplexity(input) {
+    return analyzeComplexityFallback(input);
+}
+/**
+ * Select the appropriate intent strategy based on complexity.
+ *
+ * Supports iterative refinement:
+ * - Pass 1: Detect complexity, ask blocker questions only
+ * - Pass 2+: Re-evaluate with previous answers, ask remaining questions
+ *
+ * Recommended flow for LLM-driven detection:
+ * ```typescript
+ * // 1. Get LLM prompt and send to your LLM
+ * const prompt = getComplexityDetectionPrompt(input);
+ * const llmResponse = await yourLLM.complete(prompt);
+ *
+ * // 2. Parse response
+ * const signals = parseComplexitySignalsFromLLM(llmResponse);
+ *
+ * // 3. Pass to strategy selector
+ * const strategy = selectIntentStrategy(input, context, { precomputed_signals: signals });
+ *
+ * // 4. After user answers, re-evaluate with answers
+ * const strategy2 = selectIntentStrategy(input, context, {
+ *   precomputed_signals: signals,
+ *   iteration: 2,
+ *   previous_answers: { taxonomy: "provided", approver: "manager" }
+ * });
+ * ```
+ *
+ * If no precomputed_signals provided, falls back to regex detection.
+ */
+export function selectIntentStrategy(input, context, options) {
+    // Use precomputed signals (from LLM) or fall back to regex
+    let signals = options?.precomputed_signals ?? analyzeComplexityFallback(input);
+    // Apply overrides
+    if (options?.force_complexity) {
+        signals = { ...signals, complexity: options.force_complexity };
+    }
+    if (options?.max_complexity) {
+        const levels = ["simple", "moderate", "complex"];
+        const maxIdx = levels.indexOf(options.max_complexity);
+        const currentIdx = levels.indexOf(signals.complexity);
+        if (currentIdx > maxIdx) {
+            signals = { ...signals, complexity: options.max_complexity };
+        }
+    }
+    const iteration = options?.iteration ?? 1;
+    const previousAnswers = options?.previous_answers ?? {};
+    // ═══════════════════════════════════════════════════════════════════════════
+    // BLOCKER-FIRST ITERATION
+    // - If blockers exist → ask only blockers (high-information questions)
+    // - If blockers resolved → proceed to compile
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Filter out blockers that have been answered
+    const unresolvedBlockers = signals.blockers.filter(blocker => {
+        // Check if this blocker has been resolved by previous answers
+        const resolved = Object.keys(previousAnswers).some(key => blocker.toLowerCase().includes(key.toLowerCase()) ||
+            key.toLowerCase().includes(blocker.replace(/_/g, " ").split(" ")[0]));
+        return !resolved;
+    });
+    // Determine which gates are needed based on unresolved blockers
+    const gatesToAsk = determineGatesForBlockers(unresolvedBlockers, signals.required_gates);
+    // Determine approach based on complexity and iteration
+    const approach = determineApproach(signals.complexity, unresolvedBlockers.length, iteration);
+    switch (approach) {
+        case "template_fill":
+            return {
+                complexity: signals.complexity,
+                approach: "template_fill",
+                gates_to_ask: [],
+                blockers: [],
+                safe_defaults: signals.safe_defaults,
+                reason: signals.reason,
+                signals,
+                iteration,
+                previous_answers: previousAnswers,
+            };
+        case "guided_architect":
+            return {
+                complexity: signals.complexity,
+                approach: "guided_architect",
+                gates_to_ask: gatesToAsk.slice(0, 3), // Max 3 gates for guided
+                blockers: unresolvedBlockers.slice(0, 3), // Prioritize top 3 blockers
+                safe_defaults: signals.safe_defaults,
+                prompt_package: getIntentArchitectPromptPackage(input, context),
+                reason: signals.reason,
+                signals,
+                iteration,
+                previous_answers: previousAnswers,
+            };
+        case "full_architect":
+            return {
+                complexity: signals.complexity,
+                approach: "full_architect",
+                gates_to_ask: gatesToAsk,
+                blockers: unresolvedBlockers,
+                safe_defaults: signals.safe_defaults,
+                prompt_package: getIntentArchitectPromptPackage(input, context),
+                reason: signals.reason,
+                signals,
+                iteration,
+                previous_answers: previousAnswers,
+            };
+    }
+}
+/**
+ * Determine which gates to ask based on unresolved blockers.
+ * Uses blocker-to-gate mapping from gate config.
+ */
+function determineGatesForBlockers(blockers, requiredGates) {
+    if (blockers.length === 0)
+        return [];
+    const neededGates = new Set();
+    const gates = getGateDefinitions();
+    for (const blocker of blockers) {
+        // Check which gate this blocker belongs to
+        for (const [gateNum, gateDef] of Object.entries(gates)) {
+            if (gateDef.blockers.some(b => blocker.includes(b.split("_")[0]) || b.includes(blocker.split("_")[0]))) {
+                neededGates.add(parseInt(gateNum));
+            }
+        }
+    }
+    // If we couldn't map blockers to gates, use required_gates
+    if (neededGates.size === 0) {
+        return requiredGates;
+    }
+    return Array.from(neededGates).sort((a, b) => a - b);
+}
+/**
+ * Determine the approach based on complexity, blockers, and iteration.
+ */
+function determineApproach(complexity, unresolvedBlockerCount, iteration) {
+    // If no blockers remain, can use simple template fill
+    if (unresolvedBlockerCount === 0 && iteration > 1) {
+        return "template_fill";
+    }
+    switch (complexity) {
+        case "simple":
+            return "template_fill";
+        case "moderate":
+            // Moderate with few blockers → guided
+            return unresolvedBlockerCount <= 3 ? "guided_architect" : "full_architect";
+        case "complex":
+            // Complex always starts as full, but can become guided after iteration
+            if (iteration > 1 && unresolvedBlockerCount <= 3) {
+                return "guided_architect";
+            }
+            return "full_architect";
+    }
+}
+/**
+ * Single canonical entrypoint for intent processing.
+ *
+ * Handler should call ONLY this function. It encapsulates:
+ * 1. Complexity detection (with typed scores)
+ * 2. Strategy selection (which approach to take)
+ * 3. Gate qualification (which questions to ask)
+ * 4. Prompt generation (if full architect needed)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = runIntentArchitect("Voice AI SDR that qualifies leads", {
+ *   persona_type: "voice"
+ * });
+ *
+ * if (result.strategy.can_proceed) {
+ *   // Simple enough - proceed to generation
+ * } else if (result.questions) {
+ *   // Ask qualification questions
+ *   const answers = await askUser(result.questions);
+ *   // Re-run with answers
+ *   const result2 = runIntentArchitect(input, context, {
+ *     previous_answers: answers,
+ *     iteration: 2
+ *   });
+ * } else if (result.prompt_package) {
+ *   // Full architect - send prompt to LLM
+ *   const intentSpec = await llm.complete(result.prompt_package);
+ * }
+ * ```
+ */
+export function runIntentArchitect(input, context, options) {
+    // 1. Get complexity signals (from LLM or fallback)
+    const signals = options?.precomputed_signals ?? analyzeComplexityFallback(input);
+    // 2. Get strategy using existing selectIntentStrategy
+    const strategy = selectIntentStrategy(input, context, {
+        precomputed_signals: signals,
+        max_complexity: options?.max_complexity,
+        previous_answers: options?.previous_answers,
+        iteration: options?.iteration,
+    });
+    // 3. Build assessment from signals
+    const assessment = signals.assessment ?? {
+        level: signals.complexity === "simple" ? 0.2 : signals.complexity === "moderate" ? 0.5 : 0.8,
+        confidence: {
+            kind: "confidence",
+            value: signals.detection_method === "llm" ? 0.85 : 0.6,
+            scale: "0_1",
+            rationale: signals.detection_method === "llm"
+                ? "LLM-based detection"
+                : "Regex-based fallback",
+        },
+        signals: [],
+        blockers: signals.blockers,
+        rationale: signals.reason,
+    };
+    // 4. Build strategy decision
+    const strategyDecision = {
+        approach: strategy.approach,
+        gates_to_ask: strategy.gates_to_ask,
+        blockers: signals.blockers.filter(b => !Object.keys(options?.previous_answers ?? {}).some(a => b.includes(a))),
+        can_proceed: strategy.approach === "template_fill" || strategy.gates_to_ask.length === 0,
+        next_step: strategy.approach === "template_fill"
+            ? "Proceed to workflow generation"
+            : strategy.approach === "guided_architect"
+                ? `Ask qualification questions for gates: ${strategy.gates_to_ask.join(", ")}`
+                : "Send prompt to LLM for full intent decomposition",
+    };
+    // 5. Build qualification questions from gates
+    let questions;
+    if (strategy.gates_to_ask.length > 0 && strategy.approach !== "full_architect") {
+        questions = buildQualificationQuestions(strategy.gates_to_ask, signals);
+    }
+    // 6. Build result
+    const result = {
+        assessment,
+        strategy: strategyDecision,
+        questions,
+        legacy: {
+            complexity: strategy.complexity,
+            signals,
+        },
+    };
+    // Include prompt package for full architect
+    if (strategy.approach === "full_architect" && strategy.prompt_package) {
+        result.prompt_package = strategy.prompt_package;
+    }
+    return result;
+}
+/**
+ * Build qualification questions from gate IDs
+ */
+function buildQualificationQuestions(gateIds, signals) {
+    const questions = [];
+    const gates = getGateDefinitions();
+    for (const gateId of gateIds) {
+        const gate = gates[gateId];
+        if (!gate)
+            continue;
+        // Create a question for each "ask" in the gate
+        for (let i = 0; i < gate.asks.length; i++) {
+            const ask = gate.asks[i];
+            questions.push({
+                id: `gate${gateId}_q${i + 1}`,
+                gate: gateId,
+                question: ask,
+                category: gateId <= 2 ? "WHAT" : gateId <= 4 ? "HOW" : "HOW",
+                answer_type: "text",
+                blocking: gate.type === "blocking",
+            });
+        }
+    }
+    return questions;
+}