@falai/agent 0.9.0 → 1.0.0

package/docs/core/conversation-flows/step-transitions.md

@@ -12,6 +12,138 @@ Step transitions handle:
 - **Route Completion**: Detect when routes reach their end
 - **Loop Prevention**: Avoid infinite traversal in complex flows
 
+## Stopping Conditions in Batch Execution
+
+When executing multiple steps in a batch, the engine stops for specific reasons indicated by the `stoppedReason` field in the response.
+
+### StoppedReason Values
+
+| Reason | Description | Behavior |
+|--------|-------------|----------|
+| `needs_input` | Step requires data not yet available | Batch stops, LLM generates response to collect data |
+| `end_route` | Reached END_ROUTE marker | Route is complete, no more steps to execute |
+| `route_complete` | All steps in route processed | Route finished successfully |
+| `prepare_error` | Error in prepare hook | Batch stops, error returned with last successful state |
+| `llm_error` | Error during LLM call | Batch stops, session state preserved |
+| `validation_error` | Data validation failed | Batch continues, errors included in response |
+| `finalize_error` | Error in finalize hook | Non-fatal, logged and execution continues |
+
+### Needs-Input Stopping
+
+The most common stopping condition. A step needs input when:
+
+```typescript
+// Step needs input if requires fields are missing
+const step1 = {
+  prompt: "Confirm your booking",
+  requires: ["hotel", "date"], // Both must be present
+};
+
+// Step needs input if collecting and no collect fields have data
+const step2 = {
+  prompt: "What's your preference?",
+  collect: ["preference", "notes"], // Needs input if BOTH are missing
+};
+```
+
+### End-Route Stopping
+
+Batch stops when reaching the END_ROUTE marker:
+
+```typescript
+const finalStep = confirmStep.nextStep({
+  prompt: "Booking confirmed! Anything else?",
+}).endRoute(); // Creates END_ROUTE transition
+
+// Response will have:
+// stoppedReason: "end_route"
+// isRouteComplete: true
+```
+
+### Route-Complete Stopping
+
+When all steps have been processed without hitting END_ROUTE:
+
+```typescript
+// If the last step has no transitions and doesn't need input
+const response = await agent.respond("Complete my booking");
+
+// Response will have:
+// stoppedReason: "route_complete"
+// isRouteComplete: true
+```
+
+### Transitions Within Batched Execution
+
+During batch execution, transitions work as follows:
+
+1. **Linear transitions** - Steps connected via `nextStep()` are evaluated sequentially
+2. **SkipIf evaluation** - Each step's `skipIf` is checked before inclusion
+3. **Needs-input check** - If a step needs input, batch stops there
+4. **END_ROUTE detection** - Batch stops when reaching route end
+
+```typescript
+// Example: Steps A → B → C → END_ROUTE
+// If user provides data for A and B but not C:
+
+const response = await agent.respond("Data for A and B");
+
+// Batch includes: [A, B]
+// Stops at: C (needs_input)
+// Next call will continue from C
+```
+
+### Error Stopping Conditions
+
+Errors during batch execution have different behaviors:
+
+```typescript
+// Prepare hook error - stops immediately
+const stepWithPrepare = {
+  prompt: "Processing...",
+  prepare: async (context, data) => {
+    if (!data.valid) throw new Error("Invalid data");
+  },
+};
+// stoppedReason: "prepare_error"
+// Session state: last successful state preserved
+
+// LLM error - stops with preserved state
+// stoppedReason: "llm_error"
+// Session state: preserved from before LLM call
+
+// Validation error - continues but reports error
+// stoppedReason: "validation_error"
+// Collected data: partial data preserved
+
+// Finalize hook error - logged, continues
+// stoppedReason: original reason (not changed)
+// Error: included in response for logging
+```
+
+### Checking Stop Reason in Response
+
+```typescript
+const response = await agent.respond("Book a hotel");
+
+switch (response.stoppedReason) {
+  case 'needs_input':
+    console.log("Waiting for user input");
+    break;
+  case 'end_route':
+  case 'route_complete':
+    console.log("Route finished:", response.isRouteComplete);
+    break;
+  case 'prepare_error':
+  case 'llm_error':
+    console.error("Error occurred:", response.error);
+    break;
+  case 'validation_error':
+    console.warn("Validation issues:", response.error);
+    break;
+}
+```
+
 ## Conditional Skipping
 
 ### SkipIf Logic

package/docs/core/conversation-flows/steps.md

@@ -145,6 +145,115 @@ const dataStep = previousStep.nextStep({
 });
 ```
 
+## Multi-Step Batch Execution
+
+Steps can execute together in a single LLM call when their data requirements are already satisfied. This reduces unnecessary back-and-forth and minimizes LLM costs.
+
+### How Steps Are Batched
+
+The execution engine walks through Steps sequentially and includes them in a batch until encountering a Step that needs user input:
+
+```typescript
+// Route with 3 steps
+const route = agent.createRoute({
+  title: "Booking",
+  requiredFields: ["hotel", "date", "guests"],
+  initialStep: {
+    prompt: "Which hotel?",
+    collect: ["hotel"],
+    skipIf: (data) => !!data.hotel,
+  },
+});
+
+const askDate = route.initialStep.nextStep({
+  prompt: "What date?",
+  collect: ["date"],
+  skipIf: (data) => !!data.date,
+});
+
+const askGuests = askDate.nextStep({
+  prompt: "How many guests?",
+  collect: ["guests"],
+  skipIf: (data) => data.guests !== undefined,
+});
+```
+
+When a user says "Book Grand Hotel for 2 people on Friday":
+1. Pre-extraction captures: `{ hotel: "Grand Hotel", date: "Friday", guests: 2 }`
+2. All steps have their data satisfied (skipIf evaluates to true)
+3. Route completes in a single LLM call
+
+### The `requires` Field in Batch Context
+
+The `requires` field specifies data prerequisites that must be present before a Step can execute:
+
+```typescript
+const confirmStep = askGuests.nextStep({
+  prompt: "Confirm booking for {{guests}} guests at {{hotel}} on {{date}}?",
+  requires: ["hotel", "date", "guests"], // All must be present
+  collect: ["confirmed"],
+});
+```
+
+**Batch behavior:**
+- If any `requires` field is missing from session data (after pre-extraction), the Step **needs input**
+- The batch stops at this Step, and the LLM generates a response to collect the missing data
+
+### The `collect` Field in Batch Context
+
+The `collect` field specifies which data fields the Step should extract from the conversation:
+
+```typescript
+const contactStep = {
+  prompt: "What's your email and phone?",
+  collect: ["email", "phone"], // Extract both from response
+};
+```
+
+**Batch behavior:**
+- If a Step has `collect` fields and **none** of those fields have data in the session, the Step **needs input**
+- If **any** collect field already has data, the Step doesn't need input and can be included in the batch
+
+### SkipIf Evaluation During Batch Determination
+
+The `skipIf` condition is evaluated for each Step during batch determination:
+
+```typescript
+const premiumStep = {
+  prompt: "Would you like premium features?",
+  collect: ["wantsPremium"],
+  skipIf: (data) => data.userTier === "free", // Skip for free users
+};
+```
+
+**Evaluation rules:**
+1. If `skipIf` evaluates to `true` → Step is skipped, continue to next Step
+2. If `skipIf` evaluates to `false` → Step is evaluated for needs-input
+3. If `skipIf` throws an error → Step is treated as non-skippable (safer to execute than skip)
+
+### Batch Execution Example
+
+```typescript
+// User provides partial info
+const response1 = await agent.respond("I want to book the Grand Hotel");
+
+// Response shows which steps executed
+console.log(response1.executedSteps);
+// [{ id: "ask-hotel", routeId: "booking" }]
+
+console.log(response1.stoppedReason);
+// "needs_input" - stopped at ask-date step
+
+// User provides remaining info
+const response2 = await agent.respond("2 people on Friday");
+
+console.log(response2.executedSteps);
+// [{ id: "ask-date", routeId: "booking" }, { id: "ask-guests", routeId: "booking" }]
+
+console.log(response2.stoppedReason);
+// "route_complete"
+```
+
 ## Best Practices
 
 - Keep step prompts clear and focused
@@ -152,3 +261,6 @@ const dataStep = previousStep.nextStep({
 - Leverage schema validation for data integrity
 - Implement error handling in lifecycle hooks
 - Consider user experience in step sequencing
+- Design steps to maximize batching by using `skipIf` conditions
+- Use `requires` to enforce data dependencies between steps
+- Keep `collect` fields focused on what each step actually needs