@falai/agent 0.9.2 → 1.0.1

package/src/core/BatchPromptBuilder.ts

@@ -0,0 +1,293 @@
+/**
+ * BatchPromptBuilder - Combines multiple Step prompts into a single coherent prompt
+ * 
+ * Responsible for building a combined prompt for batch execution of multiple Steps
+ * in a single LLM call.
+ * 
+ * **Validates: Requirements 4.1, 4.2, 4.3, 4.4**
+ */
+
+import type { StepOptions } from '../types/route';
+import type { AgentOptions } from '../types/agent';
+import type { SessionState } from '../types/session';
+import type { Event } from '../types/history';
+import type { Route } from './Route';
+import { render, renderMany, createTemplateContext } from '../utils/template';
+import { PromptComposer } from './PromptComposer';
+
+/**
+ * Parameters for building a batch prompt
+ */
+export interface BuildBatchPromptParams<TContext, TData> {
+  /** Steps included in this batch */
+  steps: StepOptions<TContext, TData>[];
+  /** The route containing the steps */
+  route: Route<TContext, TData>;
+  /** Conversation history */
+  history: Event[];
+  /** Agent context */
+  context: TContext;
+  /** Current session state */
+  session: SessionState<TData>;
+  /** Agent options for identity/personality */
+  agentOptions: AgentOptions<TContext, TData>;
+}
+
+/**
+ * Result of building a batch prompt
+ */
+export interface BatchPromptResult {
+  /** The combined prompt string */
+  prompt: string;
+  /** All collect fields from all steps in the batch */
+  collectFields: string[];
+  /** Number of steps included in the prompt */
+  stepCount: number;
+}
+
+/**
+ * BatchPromptBuilder class - builds combined prompts for batch execution
+ * 
+ * Combines multiple Step prompts into a single coherent prompt that:
+ * - Preserves the intent of each Step's individual prompt
+ * - Includes data collection instructions for all collect fields
+ * - Produces a single LLM call regardless of the number of Steps
+ * 
+ * **Validates: Requirements 4.1, 4.2, 4.3, 4.4**
+ */
+export class BatchPromptBuilder<TContext = unknown, TData = unknown> {
+  /**
+   * Build a combined prompt for a batch of Steps
+   * 
+   * @param params - Parameters for building the batch prompt
+   * @returns BatchPromptResult with the combined prompt and metadata
+   * 
+   * **Validates: Requirements 4.1, 4.2, 4.3, 4.4**
+   */
+  async buildBatchPrompt(params: BuildBatchPromptParams<TContext, TData>): Promise<BatchPromptResult> {
+    const { steps, route, history, context, session, agentOptions } = params;
+    
+    // Create template context for rendering
+    const templateContext = createTemplateContext<TContext, TData>({
+      context,
+      data: session.data,
+      session,
+      history,
+    });
+    
+    // Collect all collect fields from all steps
+    const collectFields: string[] = [];
+    for (const step of steps) {
+      if (step.collect && step.collect.length > 0) {
+        for (const field of step.collect) {
+          const fieldStr = String(field);
+          if (!collectFields.includes(fieldStr)) {
+            collectFields.push(fieldStr);
+          }
+        }
+      }
+    }
+    
+    // Build the combined prompt using PromptComposer for consistency
+    const composer = new PromptComposer<TContext, TData>(templateContext);
+    
+    // Add agent meta information
+    await composer.addAgentMeta(agentOptions);
+    
+    // Add route-specific identity/personality if available
+    if (route.identity) {
+      const identity = await render(route.identity, templateContext);
+      if (identity) {
+        await composer.addInstruction(`**Route Identity:** ${identity}`);
+      }
+    }
+    
+    if (route.personality) {
+      const personality = await render(route.personality, templateContext);
+      if (personality) {
+        await composer.addInstruction(`**Route Personality:** ${personality}`);
+      }
+    }
+    
+    // Add knowledge base if available
+    await composer.addKnowledgeBase(agentOptions.knowledgeBase, route.getKnowledgeBase());
+    
+    // Add glossary terms
+    const allTerms = [...(agentOptions.terms || []), ...route.getTerms()];
+    await composer.addGlossary(allTerms);
+    
+    // Add guidelines
+    const allGuidelines = [...(agentOptions.guidelines || []), ...route.getGuidelines()];
+    await composer.addGuidelines(allGuidelines);
+    
+    // Add combined rules (agent + route)
+    const allRules = [...(agentOptions.rules || []), ...route.getRules()];
+    if (allRules.length > 0) {
+      const renderedRules = await renderMany(allRules, templateContext);
+      if (renderedRules.length > 0) {
+        await composer.addInstruction(`Rules:\n- ${renderedRules.join('\n- ')}`);
+      }
+    }
+    
+    // Add combined prohibitions (agent + route)
+    const allProhibitions = [...(agentOptions.prohibitions || []), ...route.getProhibitions()];
+    if (allProhibitions.length > 0) {
+      const renderedProhibitions = await renderMany(allProhibitions, templateContext);
+      if (renderedProhibitions.length > 0) {
+        await composer.addInstruction(`Prohibitions:\n- ${renderedProhibitions.join('\n- ')}`);
+      }
+    }
+    
+    // Add interaction history
+    await composer.addInteractionHistory(history, 'Recent conversation context:');
+    
+    // Build the step sections
+    const stepSections = await this.buildStepSections(steps, templateContext);
+    
+    // Add the conversation flow section
+    if (steps.length > 1) {
+      await composer.addInstruction(
+        `## Current Conversation Flow\n\n` +
+        `You are handling multiple aspects of this conversation in a single response.\n\n` +
+        stepSections
+      );
+    } else if (steps.length === 1) {
+      await composer.addInstruction(
+        `## Current Step\n\n` +
+        stepSections
+      );
+    }
+    
+    // Add data collection section if there are fields to collect
+    if (collectFields.length > 0) {
+      const collectionSection = this.buildDataCollectionSection(collectFields, agentOptions);
+      await composer.addInstruction(collectionSection);
+    }
+    
+    // Add response format instructions
+    const responseFormat = this.buildResponseFormatSection(collectFields);
+    await composer.addInstruction(responseFormat);
+    
+    // Build the final prompt
+    const prompt = await composer.build();
+    
+    return {
+      prompt,
+      collectFields,
+      stepCount: steps.length,
+    };
+  }
+  
+  /**
+   * Build the step sections of the prompt
+   * 
+   * @param steps - Steps to include in the prompt
+   * @param templateContext - Template context for rendering
+   * @returns Formatted step sections string
+   */
+  private async buildStepSections(
+    steps: StepOptions<TContext, TData>[],
+    templateContext: ReturnType<typeof createTemplateContext<TContext, TData>>
+  ): Promise<string> {
+    const sections: string[] = [];
+    
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const stepNumber = i + 1;
+      
+      // Build step header
+      const description = step.description || `Step ${stepNumber}`;
+      let section = `### Step ${stepNumber}: ${description}\n`;
+      
+      // Render and add step prompt if available
+      if (step.prompt) {
+        const renderedPrompt = await render(step.prompt, templateContext);
+        if (renderedPrompt) {
+          section += `\n${renderedPrompt}\n`;
+        }
+      }
+      
+      // Add collect fields for this step if any
+      if (step.collect && step.collect.length > 0) {
+        const collectList = step.collect.map(f => `\`${String(f)}\``).join(', ');
+        section += `\n**Collect:** ${collectList}\n`;
+      }
+      
+      sections.push(section);
+    }
+    
+    return sections.join('\n');
+  }
+  
+  /**
+   * Build the data collection section of the prompt
+   * 
+   * @param collectFields - Fields to collect from the response
+   * @param agentOptions - Agent options containing schema information
+   * @returns Formatted data collection section string
+   */
+  private buildDataCollectionSection(
+    collectFields: string[],
+    agentOptions: AgentOptions<TContext, TData>
+  ): string {
+    const lines: string[] = [
+      '## Data Collection',
+      '',
+      'Extract the following information from your response:',
+      ''
+    ];
+    
+    // Get schema information if available
+    const schema = agentOptions.schema;
+    
+    for (const field of collectFields) {
+      let fieldDescription = field;
+      
+      // Try to get field type/description from schema
+      if (schema?.properties && schema.properties[field]) {
+        const fieldSchema = schema.properties[field] as Record<string, unknown>;
+        const rawType = fieldSchema.type;
+        const rawDescription = fieldSchema.description;
+        
+        // Safely convert to string, handling objects and primitives
+        const type = typeof rawType === 'string' ? rawType : 'string';
+        const description = typeof rawDescription === 'string' ? rawDescription : '';
+        
+        if (description) {
+          fieldDescription = `${field} (${type}): ${description}`;
+        } else {
+          fieldDescription = `${field} (${type})`;
+        }
+      }
+      
+      lines.push(`- ${fieldDescription}`);
+    }
+    
+    return lines.join('\n');
+  }
+  
+  /**
+   * Build the response format section of the prompt
+   * 
+   * @param collectFields - Fields to collect from the response
+   * @returns Formatted response format section string
+   */
+  private buildResponseFormatSection(collectFields: string[]): string {
+    const lines: string[] = [
+      '## Response Format',
+      '',
+      'Return JSON with:',
+      '- `message`: Your response to the user'
+    ];
+    
+    if (collectFields.length > 0) {
+      lines.push('');
+      lines.push('Include the following collected fields as top-level properties:');
+      for (const field of collectFields) {
+        lines.push(`- \`${field}\``);
+      }
+    }
+    
+    return lines.join('\n');
+  }
+}

package/src/core/PromptComposer.ts

@@ -1,13 +1,14 @@
 import type { Event, Term, Guideline, AgentOptions } from "../types";
 import type { Route } from "./Route";
-import { render, renderMany, formatKnowledgeBase } from "../utils/template";
+import { render, renderMany, formatKnowledgeBase, createTemplateContext } from "../utils/template";
 import { TemplateContext } from "../types/template";
+import { extractAIContextStrings, ConditionEvaluator } from "../utils/condition";
 
 export class PromptComposer<TContext = unknown, TData = unknown> {
   private parts: string[] = [];
   private renderContext: TemplateContext<TContext, TData>;
 
-  constructor(context: TemplateContext<TContext, TData> = {}) {
+  constructor(context: TemplateContext<TContext, TData> = createTemplateContext({})) {
     this.renderContext = context;
   }
 
@@ -100,22 +101,60 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
     return this;
   }
 
-  async addGuidelines(guidelines: Guideline<TContext>[]): Promise<this> {
+  async addGuidelines(guidelines: Guideline<TContext, TData>[]): Promise<this> {
     const enabled = guidelines.filter((g) => g.enabled !== false);
     if (!enabled.length) return this;
 
+    const evaluator = new ConditionEvaluator(this.renderContext);
+    const activeGuidelines: Guideline<TContext, TData>[] = [];
+    const allAIContextStrings: string[] = [];
+
+    // Evaluate guideline conditions to determine which are active
+    for (const guideline of enabled) {
+      if (guideline.condition) {
+        const evaluation = await evaluator.evaluateCondition(guideline.condition, 'AND');
+        
+        // Collect AI context strings for prompt
+        allAIContextStrings.push(...evaluation.aiContextStrings);
+        
+        // Include guideline if:
+        // 1. No programmatic conditions (only strings) - always active
+        // 2. Programmatic conditions evaluate to true
+        if (!evaluation.hasProgrammaticConditions || evaluation.programmaticResult) {
+          activeGuidelines.push(guideline);
+        }
+      } else {
+        // No condition means always active
+        activeGuidelines.push(guideline);
+      }
+    }
+
+    if (!activeGuidelines.length && !allAIContextStrings.length) return this;
+
     const renderedGuidelines = await Promise.all(
-      enabled.map(async (g, i) => {
+      activeGuidelines.map(async (g, i) => {
         const action = await render(g.action, this.renderContext);
         if (g.condition) {
-          const condition = await render(g.condition, this.renderContext);
-          return `- Guideline #${i + 1}: When ${condition}, then ${action}`;
+          // Use AI context strings if available, otherwise render the condition
+          const conditionStrings = extractAIContextStrings(g.condition);
+          if (conditionStrings.length > 0) {
+            const conditionText = conditionStrings.join(" AND ");
+            return `- Guideline #${i + 1}: When ${conditionText}, then ${action}`;
+          }
         }
         return `- Guideline #${i + 1}: ${action}`;
       })
     );
 
-    this.parts.push(`## Guidelines\n\n${renderedGuidelines.join("\n")}`);
+    // Add any additional AI context from inactive guidelines
+    if (allAIContextStrings.length > 0) {
+      const uniqueContextStrings = Array.from(new Set(allAIContextStrings));
+      const contextSection = `\n\n**Additional Context:** ${uniqueContextStrings.join(", ")}`;
+      this.parts.push(`## Guidelines\n\n${renderedGuidelines.join("\n")}${contextSection}`);
+    } else {
+      this.parts.push(`## Guidelines\n\n${renderedGuidelines.join("\n")}`);
+    }
+    
     return this;
   }
 
@@ -143,11 +182,10 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
 
     const renderedRoutes = await Promise.all(
       routes.map(async (r, i) => {
+        const whenContextStrings = r.when ? extractAIContextStrings(r.when) : [];
         const conditions =
-          r.conditions.length > 0
-            ? `\n\n  **Triggered when:** ${(
-                await renderMany(r.conditions, this.renderContext)
-              ).join(" OR ")}`
+          whenContextStrings.length > 0
+            ? `\n\n  **Triggered when:** ${whenContextStrings.join(" OR ")}`
             : "";
         const desc = r.description
           ? `\n\n  **Description:** ${r.description}`
@@ -164,12 +202,11 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
         const prohibitionsInfo =
           prohibitions.length > 0
             ? `\n\n  **Prohibitions:**\n  ${prohibitions
-                .map((x) => `  - ${x}`)
-                .join("\n  ")}`
+              .map((x) => `  - ${x}`)
+              .join("\n  ")}`
             : "";
-        return `### Route ${i + 1}: ${
-          r.title
-        }${desc}${conditions}${rulesInfo}${prohibitionsInfo}`;
+        return `### Route ${i + 1}: ${r.title
+          }${desc}${conditions}${rulesInfo}${prohibitionsInfo}`;
       })
     );
 

package/src/core/ResponseEngine.ts

@@ -10,7 +10,7 @@ import type {
 import type { Route } from "./Route";
 import type { Step } from "./Step";
 import { PromptComposer } from "./PromptComposer";
-import { render } from "../utils/template";
+import { createTemplateContext, render } from "../utils/template";
 
 export interface BuildResponsePromptParams<
   TContext = unknown,
@@ -44,36 +44,47 @@ export interface BuildFallbackPromptParams<TContext = unknown, TData = unknown>
 
 export class ResponseEngine<TContext = unknown, TData = unknown> {
   responseSchemaForRoute(
-    route: Route<TContext, TData>,
-    currentStep?: Step<TContext, TData>,
-    agentSchema?: StructuredSchema
-  ): StructuredSchema {
-    const base: StructuredSchema = {
-      type: "object",
-      properties: {
-        message: { type: "string", description: "Final user-facing message" },
-      },
-      required: ["message"],
-      additionalProperties: false,
-    };
+      route: Route<TContext, TData>,
+      currentStep?: Step<TContext, TData>,
+      agentSchema?: StructuredSchema
+    ): StructuredSchema {
+      const base: StructuredSchema = {
+        type: "object",
+        properties: {
+          message: { type: "string", description: "Final user-facing message" },
+        },
+        required: ["message"],
+        additionalProperties: false,
+      };
 
-    // Add data field only if route has responseOutputSchema
-    if (route.responseOutputSchema) {
-      base.properties!.data = route.responseOutputSchema;
-    }
+      // Add data field only if route has responseOutputSchema
+      if (route.responseOutputSchema) {
+        base.properties!.data = route.responseOutputSchema;
+      }
 
-    // Add collect fields from current step using agent-level schema
-    if (currentStep?.collect && agentSchema?.properties) {
-      for (const field of currentStep.collect) {
-        const fieldSchema = agentSchema.properties[field as string];
-        if (fieldSchema) {
-          base.properties![field as string] = fieldSchema;
+      // Add collect fields from current step
+      if (currentStep?.collect) {
+        if (agentSchema?.properties) {
+          // Use agent schema definitions for collect fields
+          for (const field of currentStep.collect) {
+            const fieldSchema = agentSchema.properties[field as string];
+            if (fieldSchema) {
+              base.properties![field as string] = fieldSchema;
+            }
+          }
+        } else {
+          // No agent schema - generate dynamic schema from collect fields
+          for (const field of currentStep.collect) {
+            base.properties![field as string] = {
+              type: "string",
+              description: `Collected value for ${String(field)}`,
+            };
+          }
         }
       }
-    }
 
-    return base;
-  }
+      return base;
+    }
 
   async buildResponsePrompt(
     params: BuildResponsePromptParams<TContext, TData>
@@ -91,8 +102,9 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
       combinedTerms,
       context,
       session,
+      agentSchema,
     } = params;
-    const templateContext = { context, session, history };
+    const templateContext = createTemplateContext({ context, session, history });
     const pc = new PromptComposer(templateContext);
 
     // Create combined agent options with route overrides
@@ -143,9 +155,136 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
 
     await pc.addInteractionHistory(history);
     await pc.addLastMessage(lastMessage);
+    
+    // Add data collection instructions - include ALL route fields, not just current step
+    // Collect all fields from route's required and optional fields
+    const allRouteFields = new Set<string>();
+    
+    if (route.requiredFields) {
+      route.requiredFields.forEach(field => allRouteFields.add(String(field)));
+    }
+    if (route.optionalFields) {
+      route.optionalFields.forEach(field => allRouteFields.add(String(field)));
+    }
+    if (currentStep?.collect) {
+      currentStep.collect.forEach(field => allRouteFields.add(String(field)));
+    }
+
+    if (allRouteFields.size > 0) {
+      const stepCollectFields = new Set(currentStep?.collect?.map(f => String(f)) || []);
+      const fieldDescriptions: string[] = [];
+      
+      for (const field of allRouteFields) {
+        if (agentSchema?.properties) {
+          const fieldSchema = agentSchema.properties[field];
+          if (fieldSchema) {
+            const fieldName = field;
+            const fieldDesc = fieldSchema.description || fieldName;
+            const fieldType = Array.isArray(fieldSchema.type) ? fieldSchema.type[0] : fieldSchema.type;
+            
+            let fieldInfo = `  • ${fieldName} (${fieldType})`;
+            
+            // Add enum values if present
+            if (fieldSchema.enum && Array.isArray(fieldSchema.enum)) {
+              fieldInfo += ` [${fieldSchema.enum.join(' | ')}]`;
+            }
+            
+            // Add description
+            fieldInfo += `: ${fieldDesc}`;
+            
+            // Mark if this is the current step's focus
+            if (stepCollectFields.has(field)) {
+              fieldInfo += ` ← FOCUS FOR THIS STEP`;
+            }
+            
+            fieldDescriptions.push(fieldInfo);
+          }
+        } else {
+          // No agent schema - generate dynamic description from field name
+          let fieldInfo = `  • ${field} (string): ${field}`;
+          if (stepCollectFields.has(field)) {
+            fieldInfo += ` ← FOCUS FOR THIS STEP`;
+          }
+          fieldDescriptions.push(fieldInfo);
+        }
+      }
+      
+      if (fieldDescriptions.length > 0) {
+        const instruction = [
+          `## Data Collection Rules`,
+          ``,
+          `CRITICAL: You MUST extract ALL relevant information from the user's message, not just what this step asks for.`,
+          ``,
+          `Available fields to extract:`,
+          ...fieldDescriptions,
+          ``,
+          `**How to collect data:**`,
+          `1. Read the user's message carefully`,
+          `2. Extract EVERY piece of information that matches ANY field above`,
+          `3. Users often provide multiple details at once (e.g., "I need a checkup next Tuesday at 2 PM")`,
+          `4. Include ALL extracted fields in your JSON response as top-level properties`,
+          `5. Field names must match EXACTLY as shown above`,
+          `6. Only include fields that the user actually mentioned`,
+          ``,
+          `**Example:** If user says "I need a checkup next Tuesday at 2 PM", extract:`,
+          `- appointmentType: "checkup"`,
+          `- preferredDate: "next Tuesday"`,
+          `- preferredTime: "2 PM"`,
+        ].join('\n');
+        
+        await pc.addInstruction(instruction);
+      }
+    }
+    
+    // Add response format instructions with explicit JSON structure
+    // Generate example JSON based on actual schema fields
+    const exampleFields: string[] = ['  "message": "your response to the user"'];
+    
+    for (const field of allRouteFields) {
+      if (agentSchema?.properties) {
+        const fieldSchema = agentSchema.properties[field];
+        if (fieldSchema) {
+          const fieldType = Array.isArray(fieldSchema.type) ? fieldSchema.type[0] : fieldSchema.type;
+          let exampleValue = '"value if extracted"';
+          
+          // Generate type-appropriate example
+          if (fieldSchema.enum && Array.isArray(fieldSchema.enum) && fieldSchema.enum.length > 0) {
+            exampleValue = `"${fieldSchema.enum[0]}"`;
+          } else if (fieldType === 'string') {
+            exampleValue = '"extracted value"';
+          } else if (fieldType === 'number' || fieldType === 'integer') {
+            exampleValue = '0';
+          } else if (fieldType === 'boolean') {
+            exampleValue = 'true';
+          }
+          
+          exampleFields.push(`  "${field}": ${exampleValue}`);
+        }
+      } else {
+        // No agent schema - use string as default
+        exampleFields.push(`  "${field}": "extracted value"`);
+      }
+    }
+    
     await pc.addInstruction(
-      "Return ONLY JSON matching the schema. The 'message' field is required."
+      [
+        `## Response Format`,
+        ``,
+        `You MUST return ONLY valid JSON in this exact format:`,
+        `{`,
+        ...exampleFields.map((f, i) => i < exampleFields.length - 1 ? `${f},` : f),
+        `}`,
+        ``,
+        `CRITICAL RULES:`,
+        `- Return ONLY the JSON object, no other text`,
+        `- The "message" field is REQUIRED and must contain your response to the user`,
+        `- Include ALL extracted data fields as top-level properties`,
+        `- Only include data fields that were actually mentioned by the user`,
+        `- Do not wrap the JSON in markdown code blocks`,
+        `- Do not add any explanatory text before or after the JSON`,
+      ].join('\n')
     );
+    
     return pc.build();
   }
 
@@ -154,7 +293,7 @@ export class ResponseEngine<TContext = unknown, TData = unknown> {
   ): Promise<string> {
     const { history, agentOptions, terms, guidelines, context, session } =
       params;
-    const templateContext = { context, session, history };
+    const templateContext = createTemplateContext({ context, session, history });
     const pc = new PromptComposer(templateContext);
 
     await pc.addAgentMeta(agentOptions);