@falai/agent 0.9.2 → 1.0.1

package/docs/architecture/multi-step-execution.md

@@ -0,0 +1,243 @@
+# Multi-Step Execution Architecture
+
+## Overview
+
+@falai/agent supports **multi-step execution**, enabling multiple consecutive Steps to execute in a single LLM call. This reduces unnecessary multi-turn conversations, minimizes LLM costs, and improves user experience when steps don't require new user input.
+
+The core insight is simple: **if a Step's data requirements are already satisfied, there's no reason to pause and wait for user input**. By detecting which Steps can execute together and combining them into a single batch, we reduce LLM calls while improving conversation UX.
+
+## Design Priorities
+
+1. **Conversation UX** - Reduce unnecessary back-and-forth
+2. **LLM Cost Optimization** - Fewer calls for the same outcome
+3. **Predictability** - Clear, simple rules for when execution pauses
+4. **Framework Understandability** - Keep the Step/Route mental model intact
+
+## Batch Execution Flow
+
+```mermaid
+flowchart TD
+    A[User Message] --> B[Pre-Extraction]
+    B --> C[Batch Determination]
+    C --> D{More Steps?}
+    D -->|Yes| E[Evaluate Step]
+    E --> F{Needs Input?}
+    F -->|No| G[Add to Batch]
+    G --> D
+    F -->|Yes| H[Stop Batch]
+    D -->|No| H
+    H --> I[Execute Prepare Hooks]
+    I --> J[Build Combined Prompt]
+    J --> K[Single LLM Call]
+    K --> L[Extract Response Data]
+    L --> M[Execute Finalize Hooks]
+    M --> N[Update Session]
+    N --> O[Return Response]
+```
+
+## Execution Phases
+
+### Phase 1: Pre-Extraction
+
+When processing a user message, the engine performs **pre-extraction** before determining the batch. This phase:
+
+1. Attempts to extract data for all fields defined in the Route's `requiredFields` and `optionalFields`
+2. Merges pre-extracted data into session data
+3. Maximizes batching by satisfying Step requirements upfront
+
+```typescript
+// User: "I want to book the Grand Hotel for 2 people next Friday"
+
+// Pre-extraction automatically captures:
+{
+  hotelName: "Grand Hotel",
+  guests: 2,
+  date: "next Friday"
+}
+```
+
+### Phase 2: Batch Determination
+
+The `BatchExecutor` walks through Steps using this algorithm:
+
+```
+For each Step starting from current position:
+  a. Check if it's END_ROUTE → stop with 'end_route'
+  b. Evaluate skipIf condition
+  c. If skipIf is true → skip Step, continue to next
+  d. If skipIf throws error → treat as non-skippable
+  e. Evaluate needsInput(step, sessionDataAfterPreExtraction)
+  f. If needsInput is false → include Step in batch, continue to next
+  g. If needsInput is true → stop with 'needs_input'
+```
+
+### Phase 3: Hook Execution (Prepare)
+
+Before the LLM call, all `prepare` hooks for batched Steps execute in Step order. If any prepare hook fails, batch execution stops immediately.
+
+### Phase 4: LLM Call
+
+A single LLM call is made with a combined prompt that includes all Step prompts and collect fields.
+
+### Phase 5: Data Collection
+
+All `collect` fields from all Steps in the batch are extracted from the LLM response and validated against the agent schema.
+
+### Phase 6: Hook Execution (Finalize)
+
+After the LLM response, all `finalize` hooks execute in Step order. Finalize hook failures are logged but don't stop execution.
+
+## Needs-Input Detection Algorithm
+
+The `needsInput` function implements the core execution rule:
+
+```typescript
+function needsInput<TData>(
+  step: Step<unknown, TData>,
+  sessionDataAfterPreExtraction: Partial<TData>
+): boolean {
+  // Check requires - all must be present (after pre-extraction)
+  if (step.requires && step.requires.length > 0) {
+    const missingRequired = step.requires.some(
+      field => sessionDataAfterPreExtraction[field] === undefined
+    );
+    if (missingRequired) return true;
+  }
+
+  // Check collect - needs input if collecting and no data exists (after pre-extraction)
+  if (step.collect && step.collect.length > 0) {
+    const hasAnyCollectData = step.collect.some(
+      field => sessionDataAfterPreExtraction[field] !== undefined
+    );
+    if (!hasAnyCollectData) return true;
+  }
+
+  return false;
+}
+```
+
+A Step **needs input** when:
+
+1. It has `requires` fields and at least one is missing from session data (after pre-extraction)
+2. It has non-empty `collect` fields and none of those fields have data (after pre-extraction)
+
+## Pre-Extraction's Role in Batching
+
+Pre-extraction is critical for maximizing batch size. Consider this scenario:
+
+```typescript
+// Route with 3 steps
+const route = agent.createRoute({
+  title: "Booking",
+  requiredFields: ["hotel", "date", "guests"],
+  steps: [
+    { prompt: "Which hotel?", collect: ["hotel"] },
+    { prompt: "What date?", collect: ["date"] },
+    { prompt: "How many guests?", collect: ["guests"] }
+  ]
+});
+
+// User message: "Book Grand Hotel for 2 people on Friday"
+```
+
+**Without pre-extraction:**
+- Step 1 needs input (no hotel data) → batch stops
+- 3 separate LLM calls needed
+
+**With pre-extraction:**
+- Pre-extraction captures: `{ hotel: "Grand Hotel", date: "Friday", guests: 2 }`
+- All steps have their data satisfied
+- All 3 steps execute in a single batch
+- 1 LLM call needed
+
+## Key Components
+
+### BatchExecutor
+
+The core component responsible for:
+- Determining which Steps can execute together (`determineBatch`)
+- Executing prepare/finalize hooks (`executePrepareHooks`, `executeFinalizeHooks`)
+- Collecting data from LLM responses (`collectBatchData`)
+- Orchestrating complete batch execution (`executeBatch`)
+
+### BatchPromptBuilder
+
+Combines multiple Step prompts into a single coherent prompt:
+- Preserves each Step's individual prompt intent
+- Includes data collection instructions for all `collect` fields
+- Produces a single LLM call regardless of Step count
+
+## Example: Multi-Step Batch
+
+```typescript
+// User provides all booking info at once
+const response = await agent.respond(
+  "I want to book the Grand Hotel for 2 people next Friday"
+);
+
+// Response includes:
+{
+  message: "Perfect! I've booked the Grand Hotel for 2 guests on Friday.",
+  executedSteps: [
+    { id: "ask-hotel", routeId: "booking" },
+    { id: "ask-date", routeId: "booking" },
+    { id: "ask-guests", routeId: "booking" }
+  ],
+  stoppedReason: "route_complete",
+  session: {
+    data: {
+      hotel: "Grand Hotel",
+      date: "Friday",
+      guests: 2
+    }
+  }
+}
+```
+
+## Debugging
+
+Enable debug mode to see batch execution decisions:
+
+```typescript
+const agent = new Agent({
+  name: "Assistant",
+  provider: provider,
+  debug: true  // Enable detailed logging
+});
+```
+
+Look for these log messages:
+
+```
+[BatchExecutor] Starting batch determination from step index 0
+[BatchExecutor] Including step ask-hotel in batch (all requirements satisfied)
+[BatchExecutor] Including step ask-date in batch (all requirements satisfied)
+[BatchExecutor] Step ask-guests needs input, stopping batch
+[BatchExecutor] Batch determination complete. Steps: 2, Stopped reason: needs_input
+```
+
+## Event Emission
+
+The BatchExecutor emits events for observability:
+
+- `batch_start` - When batch determination begins
+- `step_included` - When a step is included in the batch
+- `step_skipped` - When a step is skipped (due to skipIf)
+- `batch_stop` - When batch determination stops
+- `batch_complete` - When batch execution completes
+
+```typescript
+const executor = new BatchExecutor();
+
+executor.addEventListener((event) => {
+  console.log(`[${event.type}]`, event.details);
+});
+```
+
+---
+
+**Related Documentation:**
+- [Steps](../core/conversation-flows/steps.md) - Step configuration and batching
+- [Step Transitions](../core/conversation-flows/step-transitions.md) - Stopping conditions
+- [Data Collection](../core/conversation-flows/data-collection.md) - Pre-extraction details
+- [Prompt Composition](../core/ai-integration/prompt-composition.md) - Combined prompts

package/docs/core/agent/README.md

@@ -168,23 +168,43 @@ const agent = new Agent<CustomerContext, CustomerData>({
     },
   ],
 
-  // Behavioral guidelines
+  // Enhanced behavioral guidelines with ConditionTemplate
   guidelines: [
     {
-      condition: "Customer seems frustrated",
+      condition: [
+        "Customer seems frustrated or upset", // AI context
+        (ctx) => ctx.data?.priority === 'high' // Programmatic check
+      ],
       action: "Apologize sincerely and offer to escalate to human agent",
       enabled: true,
     },
     {
-      condition: "Premium customer requests",
+      condition: (ctx) => ctx.accountTier === 'premium', // Function-only condition
       action: "Provide expedited service and additional options",
       enabled: true,
     },
+    {
+      condition: "User is asking for help with billing", // String-only condition
+      action: "Be extra careful with financial information and offer phone support",
+      enabled: true,
+    },
   ],
 
   // Global tools available to all routes
   tools: [searchTool, userLookupTool],
 
+  // Agent-wide rules (enforced in every route)
+  rules: [
+    "Always respond in the customer's language",
+    "Confirm before taking any account action",
+  ],
+
+  // Agent-wide prohibitions (enforced in every route)
+  prohibitions: [
+    "Never share internal system details or error stack traces",
+    "Never make up information — say you don't know instead",
+  ],
+
   // Knowledge base for AI context
   knowledgeBase: {
     company: {
@@ -366,7 +386,7 @@ const agent = new Agent<CustomerContext, CustomerData>({
     {
       title: "Technical Support",
       description: "Help with technical issues",
-      conditions: ["user reports technical problem"],
+      when: ["user reports technical problem"],
       // NEW: Routes specify required fields instead of schemas
       requiredFields: ["customerName", "email", "issueType", "issueDescription"],
       optionalFields: ["phone", "priority"],
@@ -379,7 +399,7 @@ const agent = new Agent<CustomerContext, CustomerData>({
     {
       title: "Billing Inquiry", 
       description: "Handle billing and payment questions",
-      conditions: ["user asks about billing or payment"],
+      when: ["user asks about billing or payment"],
       requiredFields: ["customerName", "email", "issueType"],
       initialStep: {
         prompt:
@@ -416,6 +436,113 @@ const routes = agent.getRoutes();
 console.log(routes.map((r) => r.title)); // ["Customer Support", ...]
 ```
 
+## Enhanced Guideline System
+
+### Flexible Guideline Conditions
+
+Guidelines now support the powerful `ConditionTemplate` system, allowing for more sophisticated behavioral control:
+
+```typescript
+// String-only condition (AI context)
+agent.addGuideline({
+  condition: "User is asking for technical help",
+  action: "Provide detailed technical explanations with examples"
+});
+
+// Function-only condition (programmatic)
+agent.addGuideline({
+  condition: (ctx) => ctx.data?.userType === 'premium',
+  action: "Offer priority support and additional features"
+});
+
+// Mixed array condition (hybrid approach)
+agent.addGuideline({
+  condition: [
+    "User seems confused or needs clarification", // AI context
+    (ctx) => ctx.data?.attemptCount > 2 // Programmatic check
+  ],
+  action: "Slow down, use simpler language, and offer to connect with human support"
+});
+
+// Complex conditional guidelines
+agent.addGuideline({
+  condition: [
+    "User is reporting a critical issue", // AI context
+    (ctx) => ctx.data?.accountTier === 'enterprise', // Account check
+    (ctx) => new Date().getHours() >= 9 && new Date().getHours() <= 17 // Business hours
+  ],
+  action: "Immediately escalate to senior technical support and provide direct contact information"
+});
+```
+
+### Guideline Evaluation Logic
+
+Guidelines use **AND logic** for arrays - all conditions must be met:
+
+- **String conditions**: Provide context to AI for guideline matching
+- **Function conditions**: Must return `true` for guideline to activate
+- **Arrays**: All functions must return `true`, strings provide AI context
+
+### Context-Aware Guidelines
+
+Guidelines can access both agent context and collected data:
+
+```typescript
+interface SupportContext {
+  userTier: 'free' | 'premium' | 'enterprise';
+  supportTicketCount: number;
+  lastContactDate?: Date;
+}
+
+interface SupportData {
+  issueType?: string;
+  severity?: 'low' | 'medium' | 'high' | 'critical';
+  previousAttempts?: number;
+}
+
+agent.addGuideline({
+  condition: [
+    "User has contacted support multiple times recently", // AI context
+    (ctx) => ctx.context?.supportTicketCount > 3, // Context check
+    (ctx) => ctx.data?.severity === 'high' // Data check
+  ],
+  action: "Acknowledge their patience, apologize for the inconvenience, and prioritize their case"
+});
+```
+
+### Dynamic Guideline Activation
+
+Guidelines can be activated based on conversation state:
+
+```typescript
+// Time-based guidelines
+agent.addGuideline({
+  condition: (ctx) => {
+    const hour = new Date().getHours();
+    return hour < 9 || hour > 17; // Outside business hours
+  },
+  action: "Inform user that live support is available during business hours (9 AM - 5 PM)"
+});
+
+// Progress-based guidelines
+agent.addGuideline({
+  condition: [
+    "User is making good progress", // AI context
+    (ctx) => Object.keys(ctx.data || {}).length > 3 // Has collected significant data
+  ],
+  action: "Acknowledge their cooperation and let them know we're almost done"
+});
+
+// Route-specific guidelines
+agent.addGuideline({
+  condition: [
+    "User is in the payment process", // AI context
+    (ctx) => ctx.session?.currentRoute?.id === 'payment_flow' // Route check
+  ],
+  action: "Be extra careful with payment information and confirm all details before processing"
+});
+```
+
 ## Tool Integration
 
 ### Agent-Level Tools
@@ -644,6 +771,30 @@ const debugAgent = new Agent({
 
 @fai/agent supports hierarchical configuration where route-level options can override or merge with agent-level options. Understanding this behavior is crucial for effective agent design.
 
+### Rules and Prohibitions
+
+**Rules** and **prohibitions** are merged from both agent and route levels:
+
+- Agent-level rules/prohibitions apply to all routes
+- Route-level rules/prohibitions are appended after agent-level ones
+- Both are always included in every prompt (they are not conditional)
+
+```typescript
+const agent = new Agent({
+  rules: ["Always confirm before taking action"],
+  prohibitions: ["Never delete data without confirmation"],
+});
+
+agent.createRoute({
+  title: "Billing",
+  rules: ["Always quote prices in the user's currency"],
+  prohibitions: ["Never process refunds above $500 without escalation"],
+});
+// Result: Both agent and route rules/prohibitions are included in prompts
+```
+
+See [Rules & Prohibitions](./rules-and-prohibitions.md) for full details.
+
 ### Guidelines and Terms
 
 **Guidelines** are combined from both agent and route levels:

package/docs/core/agent/rules-and-prohibitions.md

@@ -0,0 +1,113 @@
+# Agent-Level Rules & Prohibitions
+
+## Overview
+
+Rules and prohibitions define hard behavioral boundaries for the agent. Unlike guidelines (which are conditional and advisory), rules and prohibitions are absolute — they are always included in every prompt sent to the AI provider.
+
+- **Rules**: Things the agent must always do.
+- **Prohibitions**: Things the agent must never do.
+
+Both can be defined at the agent level (applies to all routes) and at the route level (applies only within that route). When both are present, they are merged — agent-level entries appear first, followed by route-level entries.
+
+## Agent-Level Configuration
+
+```typescript
+const agent = new Agent({
+  name: "Support Bot",
+  provider: myProvider,
+
+  // Agent-wide rules — enforced in every route
+  rules: [
+    "Always respond in the user's language",
+    "Include a follow-up question when the conversation is open-ended",
+  ],
+
+  // Agent-wide prohibitions — enforced in every route
+  prohibitions: [
+    "Never share internal system details or error stack traces",
+    "Never make up information — say you don't know instead",
+  ],
+});
+```
+
+## Dynamic Templates
+
+Rules and prohibitions accept the same `Template` type used elsewhere in the framework — they can be static strings or context-aware functions:
+
+```typescript
+const agent = new Agent<MyContext, MyData>({
+  name: "Adaptive Bot",
+  provider: myProvider,
+
+  rules: [
+    "Always be polite",
+    // Dynamic rule based on context
+    ({ context }) =>
+      context?.locale === "de"
+        ? "Respond in formal German (Sie-form)"
+        : "Use a casual, friendly tone",
+  ],
+
+  prohibitions: [
+    "Never discuss competitor products",
+    // Dynamic prohibition based on collected data
+    ({ data }) =>
+      data?.isMinor
+        ? "Do not discuss age-restricted topics"
+        : "Do not share personal medical advice",
+  ],
+});
+```
+
+## Merging with Route-Level Rules
+
+Route-level rules and prohibitions are additive. The final prompt includes both:
+
+```typescript
+const agent = new Agent({
+  provider: myProvider,
+  name: "Agent",
+  rules: ["Always confirm before taking action"],
+  prohibitions: ["Never delete data without confirmation"],
+});
+
+agent.createRoute({
+  title: "Billing",
+  rules: ["Always quote prices in the user's currency"],
+  prohibitions: ["Never process refunds above $500 without escalation"],
+});
+
+// During a Billing route response, the prompt will contain:
+// Rules:
+// - Always confirm before taking action          (agent)
+// - Always quote prices in the user's currency   (route)
+//
+// Prohibitions:
+// - Never delete data without confirmation                    (agent)
+// - Never process refunds above $500 without escalation       (route)
+```
+
+This merging applies to all execution paths: single-step responses, batch execution, and streaming.
+
+## Accessing Rules Programmatically
+
+```typescript
+// Agent-level
+const agentRules = agent.getRules();
+const agentProhibitions = agent.getProhibitions();
+
+// Route-level (unchanged)
+const routeRules = route.getRules();
+const routeProhibitions = route.getProhibitions();
+```
+
+## When to Use Rules vs. Guidelines
+
+| | Rules / Prohibitions | Guidelines |
+|---|---|---|
+| Scope | Always active | Conditional (can have `condition`) |
+| Purpose | Hard boundaries | Soft behavioral nudges |
+| Enforcement | Included in every prompt | Only when condition matches |
+| Example | "Never reveal API keys" | "When user is frustrated, apologize" |
+
+Use rules for non-negotiable constraints. Use guidelines for context-dependent behavior.

package/docs/core/agent/session-management.md

@@ -589,7 +589,7 @@ For simple question-answering without step:
 ```typescript
 const qnaRoute = agent.createRoute({
   title: "Company Q&A",
-  conditions: ["User asks about company"],
+  when: ["User asks about company"],
   // NO schema - stepless!
 });