mojulo 0.0.0 → 0.1.0

package/lib/builder/evaluator.js

@@ -0,0 +1,159 @@
+/**
+ * Smart Intent Evaluator
+ *
+ * LLM-based evaluation of user intent to determine assistance level.
+ * Lightweight - only analyzes the user's message and whether documents are attached.
+ * Does NOT read document contents - that's handled downstream.
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+
+const EVALUATOR_MODEL = 'claude-sonnet-4-20250514';
+const EVALUATOR_MAX_TOKENS = 1024;
+
+/**
+ * Evaluation prompt template
+ */
+const EVALUATOR_PROMPT = `You are an intent evaluator for a bot-building platform. Analyze the user's message to determine:
+
+1. **Assistance Level**: Does this user need high assistance (guided flow) or low assistance (direct orchestration)?
+
+**High Assistance** indicators:
+- Vague or minimal instructions ("make a bot with this", "use this document")
+- Questions about what to do ("what can you do with this?", "how should I set this up?")
+- No specific bot configuration mentioned
+- First-time user language
+- Documents attached but no clear direction on how to use them
+
+**Low Assistance** indicators:
+- Specific bot requirements stated (name, purpose, fields to collect)
+- Clear flow type mentioned (lead capture, appointment booking, support bot)
+- Technical specificity (mentions webhooks, forms, specific integrations)
+- Multiple configuration details provided
+- Confident, directive language
+
+2. **Extracted Context**: Pull out any actionable configuration from the user's message:
+- Bot name or naming hints ("called X", "named X")
+- Organization/company name ("for Acme Corp")
+- Bot purpose or objective
+- Flow type (support, lead gen, appointments, FAQ, etc.)
+- Specific fields or data to collect
+- Greeting or tone preferences
+
+Respond in this exact format:
+
+ASSISTANCE_LEVEL: [high|low]
+
+CONTEXT:
+[Free-form text with extracted configuration context. Be specific and actionable. This will be passed to the main bot configuration assistant to use as defaults.]
+
+REASONING:
+[Brief explanation of why you classified the assistance level this way]`;
+
+/**
+ * Evaluate user intent and extract context
+ *
+ * @param {string} userMessage - The user's input message
+ * @param {boolean} hasDocuments - Whether documents are attached
+ * @returns {Promise<{ assistanceLevel: 'high' | 'low', context: string, reasoning: string }>}
+ */
+export async function evaluateIntent(userMessage, hasDocuments = false) {
+  const apiKey = process.env.BUILDER_ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    console.warn('[Evaluator] No API key, defaulting to high assistance');
+    return {
+      assistanceLevel: 'high',
+      context: '',
+      reasoning: 'API key not configured, defaulting to guided flow',
+    };
+  }
+
+  // Build the evaluation input - just message + document presence metadata
+  let evaluationInput = `USER MESSAGE:\n${userMessage}`;
+
+  if (hasDocuments) {
+    evaluationInput += `\n\n[Documents are attached to this message]`;
+  }
+
+  try {
+    const client = new Anthropic({ apiKey });
+
+    const response = await client.messages.create({
+      model: EVALUATOR_MODEL,
+      max_tokens: EVALUATOR_MAX_TOKENS,
+      messages: [
+        {
+          role: 'user',
+          content: evaluationInput,
+        },
+      ],
+      system: EVALUATOR_PROMPT,
+    });
+
+    const responseText = response.content
+      .filter((block) => block.type === 'text')
+      .map((block) => block.text)
+      .join('\n');
+
+    return parseEvaluatorResponse(responseText);
+  } catch (error) {
+    console.error('[Evaluator] LLM call failed:', error.message);
+    // Fallback to high assistance on error
+    return {
+      assistanceLevel: 'high',
+      context: '',
+      reasoning: `Evaluation failed (${error.message}), defaulting to guided flow`,
+    };
+  }
+}
+
+/**
+ * Parse the evaluator's response into structured format
+ *
+ * @param {string} responseText - Raw response from evaluator LLM
+ * @returns {{ assistanceLevel: 'high' | 'low', context: string, reasoning: string }}
+ */
+function parseEvaluatorResponse(responseText) {
+  // Extract assistance level
+  const levelMatch = responseText.match(/ASSISTANCE_LEVEL:\s*(high|low)/i);
+  const assistanceLevel = levelMatch ? levelMatch[1].toLowerCase() : 'high';
+
+  // Extract context section
+  const contextMatch = responseText.match(/CONTEXT:\s*([\s\S]*?)(?=REASONING:|$)/i);
+  const context = contextMatch ? contextMatch[1].trim() : responseText;
+
+  // Extract reasoning section
+  const reasoningMatch = responseText.match(/REASONING:\s*([\s\S]*?)$/i);
+  const reasoning = reasoningMatch ? reasoningMatch[1].trim() : 'No reasoning provided';
+
+  return {
+    assistanceLevel,
+    context,
+    reasoning,
+  };
+}
+
+/**
+ * Quick heuristic check to determine if evaluation is needed
+ * (Skip evaluation for obvious cases to save latency)
+ *
+ * @param {string} userMessage - The user's input message
+ * @param {boolean} hasDocuments - Whether documents are attached
+ * @returns {{ skipEvaluation: boolean, defaultLevel: 'high' | 'low' | null }}
+ */
+export function shouldSkipEvaluation(userMessage, hasDocuments) {
+  const wordCount = userMessage.split(/\s+/).filter((w) => w.length > 0).length;
+
+  // Very short message with documents = definitely high assistance
+  if (hasDocuments && wordCount <= 10) {
+    return { skipEvaluation: true, defaultLevel: 'high' };
+  }
+
+  // Very detailed message (100+ words) = definitely low assistance
+  if (wordCount >= 100) {
+    return { skipEvaluation: true, defaultLevel: 'low' };
+  }
+
+  // Otherwise, run the evaluator
+  return { skipEvaluation: false, defaultLevel: null };
+}

package/lib/builder/executor.js

@@ -0,0 +1,252 @@
+/**
+ * Builder Save Executor
+ *
+ * Persists a builder session as a deployment row in SQLite. Does NOT build
+ * the ZIP artifact — that's a separate, on-demand step (see
+ * `lib/deployers/build.js` and `POST /api/deployments/[id]/build`).
+ *
+ * The chat UI surfaces a "Build & Download" CTA after this returns.
+ */
+
+import { BuilderSessionRepository } from '../db/repositories/builderSessions.js';
+import {
+  DeploymentRepository,
+  DEPLOYMENT_STATUS,
+} from '../db/repositories/deployments.js';
+import { DeploymentEventRepository } from '../db/repositories/deploymentEvents.js';
+import { ApiKeyRepository } from '../db/repositories/apiKeys.js';
+import { decryptApiKey, generateApiKey } from '../deployment-auth.js';
+import { composeAndCache, getBuilderSession, validateForDeployment } from './session.js';
+import { buildLLMConfig } from '../config-builder.js';
+
+/**
+ * Save a modular session as a deployment row.
+ *
+ * @param {string} sessionId
+ * @param {string} userId
+ * @param {Object} options
+ * @param {string} [options.botSpaceId]
+ * @param {string} [options.redeploymentId] - If provided, update existing row
+ * @returns {Promise<Object>}
+ */
+export async function saveBuilderConfig(sessionId, userId, options = {}) {
+  const { botSpaceId, redeploymentId } = options;
+  const isUpdate = !!redeploymentId;
+
+  const session = await getBuilderSession(sessionId, userId);
+
+  const validation = await validateForDeployment(sessionId, userId);
+  if (!validation.valid) {
+    throw new Error(`Session not ready to save: ${validation.errors.join(', ')}`);
+  }
+
+  const { instructions } = await composeAndCache(sessionId, userId);
+
+  const apiKeyRecords = await ApiKeyRepository.findByUserId(userId);
+  const apiKeyRecord = apiKeyRecords.find(
+    (key) => key.provider === session.coreConfig.provider
+  );
+  if (!apiKeyRecord) {
+    throw new Error(`No API key found for provider: ${session.coreConfig.provider}`);
+  }
+  const decryptedApiKey = decryptApiKey(apiKeyRecord.encryptedKey);
+
+  const deploymentConfig = buildDeploymentConfig(session, instructions, decryptedApiKey);
+  const documentIds = session.protocolData.knowledge?.documents?.map((d) => d.id) || [];
+  const enabledProtocols = session.enabledProtocols;
+
+  // All bots run vector retrieval. Knowledge protocol embeds documents;
+  // triage protocol embeds route descriptions; both end up in the same
+  // single cosine index. A bot with neither protocol simply has no
+  // embeddings — RAG is silently disabled at runtime in that case.
+  const ragMode = 'vector';
+  const embeddings = session.generatedConfigs?.embeddings || null;
+  if (enabledProtocols.knowledge && !embeddings?.storageKey) {
+    throw new Error(
+      'Knowledge protocol is enabled but no embeddings were produced. Run process_documents first.'
+    );
+  }
+  if (enabledProtocols.triage && !embeddings?.storageKey) {
+    throw new Error(
+      'Triage protocol is enabled but no embeddings were produced. Run generate_triage_config first.'
+    );
+  }
+
+  let deployment;
+  let deploymentApiKey;
+
+  if (isUpdate) {
+    const existing = await DeploymentRepository.findById(redeploymentId);
+    if (!existing) {
+      throw new Error(`Deployment ${redeploymentId} not found`);
+    }
+    if (existing.userId && existing.userId !== userId) {
+      throw new Error('Unauthorized to update this deployment');
+    }
+
+    deploymentApiKey = existing.apiKey;
+
+    deployment = await DeploymentRepository.update(redeploymentId, {
+      botName: session.coreConfig.botName,
+      config: {
+        ...deploymentConfig,
+        _modular: {
+          paradigm: 'modular',
+          enabledProtocols,
+          sessionId,
+        },
+      },
+      documentIds,
+      error: null,
+    });
+  } else {
+    deploymentApiKey = generateApiKey();
+    deployment = await DeploymentRepository.create({
+      userId,
+      botSpaceId: botSpaceId || null,
+      botName: session.coreConfig.botName,
+      flowType: 'modular',
+      status: DEPLOYMENT_STATUS.SAVED,
+      config: {
+        ...deploymentConfig,
+        _modular: {
+          paradigm: 'modular',
+          enabledProtocols,
+          sessionId,
+        },
+      },
+      documentIds,
+      apiKey: deploymentApiKey,
+    });
+  }
+
+  // Stamp embedding pointers onto the row. ragMode is always 'vector' now;
+  // setRagMode is kept as a no-op write so legacy rows keep their schema.
+  await DeploymentRepository.setRagMode(deployment.id, ragMode);
+  if (embeddings?.storageKey) {
+    await DeploymentRepository.setEmbeddings(deployment.id, {
+      storageKey: embeddings.storageKey,
+      model: embeddings.model,
+      chunkCount: embeddings.chunkCount,
+    });
+  } else {
+    await DeploymentRepository.clearEmbeddings(deployment.id);
+  }
+  // Re-fetch so the returned deployment reflects the embedding columns.
+  deployment = await DeploymentRepository.findById(deployment.id);
+
+  await BuilderSessionRepository.linkDeployment(sessionId, userId, deployment.id);
+  await DeploymentEventRepository.create({
+    deploymentId: deployment.id,
+    userId,
+    eventType: isUpdate ? 'updated' : 'created',
+    status: deployment.status,
+    config: deployment.config,
+  });
+
+  await BuilderSessionRepository.updateStepProgress(
+    sessionId,
+    userId,
+    'deploy',
+    'completed'
+  );
+
+  return {
+    success: true,
+    deploymentId: deployment.id,
+    status: deployment.status,
+    botName: session.coreConfig.botName,
+    sessionId,
+    isUpdate,
+    buildUrl: `/api/deployments/${deployment.id}/build`,
+    downloadUrl: `/api/deployments/${deployment.id}/download`,
+  };
+}
+
+/**
+ * Build deployment config from session data
+ * Produces the nested structure expected by validateDeploymentConfig:
+ * { config: {...}, llm: { provider, [provider]: {...} }, objective, ... }
+ */
+function buildDeploymentConfig(session, instructions, apiKey) {
+  const { coreConfig, identityConfig, enabledProtocols, protocolData, generatedConfigs } = session;
+
+  const provider = coreConfig.provider || 'anthropic';
+  const model = coreConfig.model || 'claude-sonnet-4-20250514';
+
+  const configSection = {
+    instructions: './config/instructions.txt',
+    name: coreConfig.botName,
+    chatDisplayName: identityConfig.chatDisplayName || 'Bot',
+    placeholder: 'Type your message...',
+    firstMessage: identityConfig.firstMessage || `Welcome! I'm ${coreConfig.botName}. How can I help you?`,
+    suggestedPrompts: (identityConfig.suggestedPrompts || []).map((prompt) =>
+      typeof prompt === 'string' ? { suggestedPrompt: prompt } : prompt
+    ),
+    actionsBar: {
+      showBar: false,
+      showSourceButton: false,
+      showMetadataButton: false,
+      showCopyButton: false,
+      showSuggestedPrompts: false,
+    },
+  };
+
+  if (enabledProtocols.formGathering && protocolData.formGathering) {
+    configSection.isForm = true;
+    configSection.formStructure = './config/formFormat.json';
+    if (protocolData.formGathering.formCompletionWebhook) {
+      configSection.formCompletionWebhook = protocolData.formGathering.formCompletionWebhook;
+    }
+    configSection.afterSubmitChatMessage = protocolData.formGathering.afterSubmitChatMessage;
+    if (protocolData.formGathering.formSendHome) {
+      configSection.formSendHome = true;
+    }
+  }
+
+  if (enabledProtocols.appointments && protocolData.appointments) {
+    configSection.isCalendar = true;
+    configSection.calendarConfig = './config/calendarConfig.json';
+  }
+
+  if (enabledProtocols.triage && protocolData.triage) {
+    configSection.isTriage = true;
+    configSection.triageRoutes = './config/triageRoutes.json';
+  }
+
+  // Optical Read: chat-builder writes opticalRead.fields onto generatedConfigs
+  // (see generate_optical_read_config). Wire the artifact-side flag/path here
+  // and surface the field list at top-level for build.js to pick up.
+  const opticalReadFields = enabledProtocols.opticalRead
+    ? generatedConfigs?.opticalRead?.fields || []
+    : [];
+  if (enabledProtocols.opticalRead && opticalReadFields.length > 0) {
+    configSection.isOpticalRead = true;
+    configSection.opticalReadFields = './config/opticalReadFields.json';
+    // Default the upload-first entry point on for chat-builder output. The
+    // chat builder doesn't expose a per-bot toggle; users can opt out by
+    // editing the deployment in the wizard, which respects the saved value.
+    configSection.opticalReadShowUploadOnStart = true;
+  }
+
+  return {
+    config: configSection,
+    llm: buildLLMConfig(provider, apiKey, model, {}),
+    objective: identityConfig.objective,
+    botSummary: generatedConfigs?.botSummary || '',
+    formStructure: enabledProtocols.formGathering
+      ? protocolData.formGathering?.generatedFormJson
+      : undefined,
+    formCompletionWebhook: protocolData.formGathering?.formCompletionWebhook || undefined,
+    afterSubmitChatMessage: protocolData.formGathering?.afterSubmitChatMessage || undefined,
+    formSendHome: protocolData.formGathering?.formSendHome || undefined,
+    appointmentDestinations: enabledProtocols.appointments
+      ? protocolData.appointments?.destinations
+      : undefined,
+    triageRoutes: enabledProtocols.triage ? protocolData.triage?.routes : undefined,
+    opticalReadFields: enabledProtocols.opticalRead ? opticalReadFields : undefined,
+    paradigm: 'modular',
+    enabledProtocols,
+    _composedInstructions: instructions,
+  };
+}

package/lib/builder/index.js

@@ -0,0 +1,48 @@
+/**
+ * Builder Flow Entry Point
+ *
+ * Exports all builder functionality for the protocol-aware wizard system.
+ * Supports both legacy step-card wizard and inverted flow ("Claude proposes, User disposes").
+ */
+
+// Session management (legacy wizard mode)
+export {
+  createBuilderSession,
+  getBuilderSession,
+  toggleProtocol,
+  generateStepFlow,
+  saveCoreConfig,
+  saveIdentityConfig,
+  saveProtocolConfig,
+  composeAndCache,
+  validateForDeployment,
+  deleteBuilderSession,
+} from './session.js';
+
+// Composer bridge
+export { composeFromSession, previewComposition } from './composer-bridge.js';
+
+// Validators
+export {
+  PROTOCOL_VALIDATORS,
+  validateCoreConfig,
+  validateIdentityConfig,
+  validateEnabledProtocols,
+  validateSessionForDeployment,
+} from './validators.js';
+
+// Save executor (formerly the deployment executor — now writes to SQLite only;
+// callers that want a built artifact must hit /api/deployments/[id]/build).
+export { saveBuilderConfig } from './executor.js';
+
+// Inverted flow tools
+export { BUILDER_TOOLS, TOOL_LABELS, TOOL_ICONS, getToolByName, validateToolInput } from './tools.js';
+
+// Inverted flow tool executors
+export { executeBuilderTool, builderToolHandlers } from './tool-executors.js';
+
+// Inverted flow system prompt
+export { buildBuilderSystemPrompt } from './system-prompt.js';
+
+// Smart intent evaluation
+export { evaluateIntent, shouldSkipEvaluation } from './evaluator.js';

package/lib/builder/session.js

@@ -0,0 +1,248 @@
+/**
+ * Session Manager for Builder Flow
+ *
+ * High-level session management functions that orchestrate
+ * repository operations and business logic.
+ */
+
+import { BuilderSessionRepository } from '../db/repositories/builderSessions.js';
+import { composeFromSession } from './composer-bridge.js';
+import { validateSessionForDeployment, PROTOCOL_VALIDATORS } from './validators.js';
+
+/**
+ * Create a new builder session
+ * @param {string|null} orgId - Organization ID (optional)
+ * @param {string} userId - User ID
+ * @returns {Promise<Object>} Created session
+ */
+export async function createBuilderSession(orgId, userId) {
+  return BuilderSessionRepository.create({ userId });
+}
+
+/**
+ * Get session with access check
+ * @param {string} sessionId - Session ID
+ * @param {string} userId - User ID
+ * @returns {Promise<Object>} Session object
+ * @throws {Error} If session not found or access denied
+ */
+export async function getBuilderSession(sessionId, userId) {
+  const session = await BuilderSessionRepository.findByIdAndUserId(sessionId, userId);
+  if (!session) {
+    throw new Error('Session not found or access denied');
+  }
+  return session;
+}
+
+/**
+ * Toggle protocol and regenerate step flow
+ * @param {string} sessionId - Session ID
+ * @param {string} userId - User ID
+ * @param {string} protocol - Protocol name
+ * @param {boolean} enabled - Enable or disable
+ * @returns {Promise<{ session: Object, steps: Array }>}
+ */
+export async function toggleProtocol(sessionId, userId, protocol, enabled) {
+  const session = await getBuilderSession(sessionId, userId);
+
+  const enabledProtocols = {
+    ...session.enabledProtocols,
+    [protocol]: enabled,
+  };
+
+  const updatedSession = await BuilderSessionRepository.updateProtocols(
+    sessionId,
+    userId,
+    enabledProtocols
+  );
+
+  // Return updated session with regenerated step list
+  return {
+    session: updatedSession,
+    steps: generateStepFlow(updatedSession.enabledProtocols),
+  };
+}
+
+/**
+ * Generate step flow based on enabled protocols
+ * @param {Object} enabledProtocols - Protocol toggles
+ * @returns {Array} Array of step objects
+ */
+export function generateStepFlow(enabledProtocols) {
+  const steps = [
+    { id: 'core', number: 1, section: 'Bot Setup', required: true },
+    { id: 'protocols', number: 2, section: 'Capabilities', required: true },
+    { id: 'identity', number: 3, section: 'Identity', required: true },
+  ];
+
+  let stepNumber = 4;
+
+  if (enabledProtocols.knowledge) {
+    steps.push({
+      id: 'knowledge',
+      number: stepNumber++,
+      section: 'Knowledge Base',
+      protocol: 'knowledge',
+    });
+  }
+
+  if (enabledProtocols.formGathering) {
+    steps.push({
+      id: 'formGathering',
+      number: stepNumber++,
+      section: 'Form Collection',
+      protocol: 'formGathering',
+    });
+  }
+
+  if (enabledProtocols.appointments) {
+    steps.push({
+      id: 'appointments',
+      number: stepNumber++,
+      section: 'Appointments',
+      protocol: 'appointments',
+    });
+  }
+
+  steps.push({
+    id: 'deploy',
+    number: stepNumber,
+    section: 'Deploy',
+    required: true,
+  });
+
+  return steps;
+}
+
+/**
+ * Save core configuration
+ * @param {string} sessionId - Session ID
+ * @param {string} userId - User ID
+ * @param {Object} config - Core configuration
+ * @returns {Promise<Object>} Updated session
+ */
+export async function saveCoreConfig(sessionId, userId, config) {
+  await getBuilderSession(sessionId, userId); // Access check
+
+  const updatedSession = await BuilderSessionRepository.updateCoreConfig(
+    sessionId,
+    userId,
+    config
+  );
+
+  // Mark step as completed
+  await BuilderSessionRepository.updateStepProgress(sessionId, userId, 'core', 'completed');
+
+  return updatedSession;
+}
+
+/**
+ * Save identity configuration
+ * @param {string} sessionId - Session ID
+ * @param {string} userId - User ID
+ * @param {Object} config - Identity configuration
+ * @returns {Promise<Object>} Updated session
+ */
+export async function saveIdentityConfig(sessionId, userId, config) {
+  await getBuilderSession(sessionId, userId); // Access check
+
+  const updatedSession = await BuilderSessionRepository.updateIdentityConfig(
+    sessionId,
+    userId,
+    config
+  );
+
+  await BuilderSessionRepository.updateStepProgress(sessionId, userId, 'identity', 'completed');
+
+  return updatedSession;
+}
+
+/**
+ * Save protocol-specific configuration
+ * @param {string} sessionId - Session ID
+ * @param {string} userId - User ID
+ * @param {string} protocol - Protocol name
+ * @param {Object} data - Protocol data
+ * @returns {Promise<Object>} Updated session
+ */
+export async function saveProtocolConfig(sessionId, userId, protocol, data) {
+  const session = await getBuilderSession(sessionId, userId);
+
+  // Validate protocol data
+  if (PROTOCOL_VALIDATORS[protocol]) {
+    const validation = PROTOCOL_VALIDATORS[protocol](data);
+    if (!validation.valid) {
+      throw new Error(validation.error);
+    }
+  }
+
+  const updatedSession = await BuilderSessionRepository.updateProtocolData(
+    sessionId,
+    userId,
+    protocol,
+    data
+  );
+
+  // Mark protocol step as completed
+  await BuilderSessionRepository.updateStepProgress(sessionId, userId, protocol, 'completed');
+
+  return updatedSession;
+}
+
+/**
+ * Compose instructions and cache them
+ * @param {string} sessionId - Session ID
+ * @param {string} userId - User ID
+ * @returns {Promise<{ instructions: string, responseFormat: string, protocolsIncluded: string[], cached: boolean }>}
+ */
+export async function composeAndCache(sessionId, userId) {
+  const session = await getBuilderSession(sessionId, userId);
+
+  // Check if cached instructions are still valid
+  if (session.composedInstructions) {
+    return {
+      instructions: session.composedInstructions,
+      responseFormat: session.responseFormat,
+      cached: true,
+    };
+  }
+
+  // Compose new instructions
+  const { instructions, responseFormat, protocolsIncluded } = await composeFromSession(session);
+
+  // Cache them
+  await BuilderSessionRepository.cacheComposedInstructions(
+    sessionId,
+    userId,
+    instructions,
+    responseFormat
+  );
+
+  return {
+    instructions,
+    responseFormat,
+    protocolsIncluded,
+    cached: false,
+  };
+}
+
+/**
+ * Validate session is ready for deployment
+ * @param {string} sessionId - Session ID
+ * @param {string} userId - User ID
+ * @returns {Promise<{ valid: boolean, errors: string[] }>}
+ */
+export async function validateForDeployment(sessionId, userId) {
+  const session = await getBuilderSession(sessionId, userId);
+  return validateSessionForDeployment(session);
+}
+
+/**
+ * Delete a session
+ * @param {string} sessionId - Session ID
+ * @param {string} userId - User ID
+ * @returns {Promise<boolean>} True if deleted
+ */
+export async function deleteBuilderSession(sessionId, userId) {
+  return BuilderSessionRepository.delete(sessionId, userId);
+}