@falai/agent 0.9.0 → 1.0.0

package/docs/api/overview.md

@@ -12,7 +12,7 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
   - [RoutingEngine](#routingengine)
   - [ResponseEngine](#responseengine)
   - [PromptComposer](#promptcomposer)
-  - [ToolExecutor](#toolexecutor)
+
 - [AI Providers](#ai-providers)
 - [Persistence Adapters](#persistence-adapters)
 - [Types & Interfaces](#types--interfaces)
@@ -136,9 +136,58 @@ for await (const chunk of agent.stream("Hello")) {
 ##### Tool Management
 
 ```typescript
-createTool(tool: Tool<TContext, unknown[], unknown, unknown>): this
-registerTools(tools: Tool<TContext, unknown[], unknown, unknown>[]): this
-getTools(): Tool<TContext, unknown[], unknown, unknown>[]
+addTool(definition: Tool<TContext, TData, TResult>): this
+tool: ToolManager<TContext, TData> // Access to ToolManager instance
+```
+
+**Comprehensive Tool Examples:**
+
+```typescript
+// 1. Simple return value (most common)
+agent.addTool({
+  id: "calculate_tip",
+  description: "Calculate tip amount",
+  handler: async ({ context, data }, args) => {
+    const tip = args.amount * args.percentage;
+    return `Tip: $${tip.toFixed(2)}`; // Simple string return
+  }
+});
+
+// 2. Complex ToolResult pattern
+agent.addTool({
+  id: "process_order",
+  description: "Process customer order",
+  handler: async ({ context, data }, args) => {
+    const order = await orderService.process(args.items);
+    return {
+      data: `Order ${order.id} processed successfully`,
+      success: true,
+      contextUpdate: { lastOrderId: order.id },
+      dataUpdate: { orderStatus: 'processed' }
+    }; // Detailed ToolResult object
+  }
+});
+
+// 3. Registry for reuse
+agent.tool.register({
+  id: "send_notification",
+  description: "Send notification to user",
+  handler: async ({ context }, args) => {
+    await notificationService.send(context.userId, args.message);
+    return "Notification sent"; // Simple return
+  }
+});
+
+// 4. Pattern helper
+const validationTool = agent.tool.createValidation({
+  id: "validate_email",
+  fields: ['email'],
+  validator: async (context, data) => ({
+    valid: /\S+@\S+\.\S+/.test(data.email),
+    errors: []
+  })
+});
+agent.tool.register(validationTool);
 ```
 
 ##### Domain Knowledge
@@ -301,9 +350,7 @@ getRoutingExtrasSchema(): StructuredSchema | undefined
 ##### Tool Management
 
 ```typescript
-createTool(tool: Tool<TContext, unknown[], unknown, TData>): this
-registerTools(tools: Tool<TContext, unknown[], unknown, TData>[]): this
-getTools(): Tool<TContext, unknown[], unknown, TData>[]
+addTool(definition: Tool<TContext, TData, TResult>): this
 ```
 
 ##### Lifecycle Hooks
@@ -371,11 +418,59 @@ getTransitions(): Step<TContext, TData>[]
 
 ```typescript
 getRef(): StepRef
-asStepResult(): StepResult<TContext, TData>
 ```
 
 ---
 
+### StepResult
+
+Result interface returned by step transition methods that enables fluent chaining of conversation flows.
+
+#### Interface
+
+```typescript
+interface StepResult<TContext = unknown, TData = unknown> extends StepRef {
+  nextStep: (spec: StepOptions<TContext, TData>) => StepResult<TContext, TData>;
+  branch: (branches: BranchSpec<TContext, TData>[]) => BranchResult<TContext, TData>;
+  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
+}
+```
+
+#### Methods
+
+##### Chaining
+
+```typescript
+nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData>
+```
+
+Creates a transition and returns a chainable result for building linear flows.
+
+##### Branching
+
+```typescript
+branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>
+```
+
+Creates multiple conditional branches for complex conversation flows.
+
+##### Route Completion
+
+```typescript
+endRoute(options?: Omit<StepOptions<TContext, TData>, "step">): StepResult<TContext, TData>
+```
+
+Shortcut method to end the current route with optional completion configuration.
+
+#### Properties
+
+Inherits from `StepRef`:
+
+- `id: string` - Step identifier
+- `routeId: string` - Route this step belongs to
+
+---
+
 ### RoutingEngine
 
 AI-powered routing system that intelligently selects routes and steps based on conversation context.
@@ -505,23 +600,7 @@ addDirectives(directives?: string[]): Promise<this>
 build(): Promise<string>
 ```
 
----
-
-### ToolExecutor
-
-Handles tool execution with context updates and data collection.
 
-#### Methods
-
-```typescript
-executeTool(params: {
-  tool: Tool;
-  context: unknown;
-  updateContext: (updates: Partial<unknown>) => Promise<void>;
-  history: Event[];
-  data: unknown;
-}): Promise<ToolExecutionResult>
-```
 
 ---
 
@@ -695,7 +774,8 @@ interface RouteOptions<TContext = unknown, TData = unknown> {
   description?: string;
   identity?: Template<TContext, TData>;
   personality?: Template<TContext, TData>;
-  conditions?: Template<TContext, TData>[];
+  when?: ConditionTemplate<TContext, TData>;
+  skipIf?: ConditionTemplate<TContext, TData>;
   rules?: Template<TContext, TData>[];
   prohibitions?: Template<TContext, TData>[];
   
@@ -737,6 +817,31 @@ interface StepOptions<TContext = unknown, TData = unknown> {
   tools?: (string | Tool<TContext, unknown[], unknown, TData>)[];
 }
 
+interface StepResult<TContext = unknown, TData = unknown> extends StepRef {
+  nextStep: (spec: StepOptions<TContext, TData>) => StepResult<TContext, TData>;
+  branch: (branches: BranchSpec<TContext, TData>[]) => BranchResult<TContext, TData>;
+  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
+}
+
+interface BranchResult<TContext = unknown, TData = unknown> {
+  [branchName: string]: StepResult<TContext, TData>;
+}
+
+interface BranchSpec<TContext = unknown, TData = unknown> {
+  name: string;
+  id?: string;
+  step: StepOptions<TContext, TData>;
+}
+
+interface StepRef {
+  id: string;
+  routeId: string;
+}
+
+interface RouteRef {
+  id: string;
+}
+
 // ==============================================================================
 // LIFECYCLE HOOKS: prepare & finalize
 // ==============================================================================
@@ -756,21 +861,33 @@ interface StepOptions<TContext = unknown, TData = unknown> {
   }
 }
 
-// Example: Using existing tools (new approach)
+// Example: Using existing tools (unified Tool interface)
 {
-  prepare: "validate_user_data",  // Tool ID string
-  finalize: myCustomTool,         // Tool object
+  prepare: "validate_user_data",  // Tool ID string - simple return value
+  finalize: "send_notification",  // Tool ID string - ToolResult pattern
 }
 
-// Example: Inline tool definition
+// Example: Inline tool definition with flexible returns
 {
   prepare: {
     id: "setup_step_context",
     description: "Prepare context for this step",
     parameters: { type: "object", properties: {} },
     handler: ({ context, data }) => {
-      // Custom logic here
-      return { data: "Setup complete" };
+      // Simple return value
+      return "Setup complete";
+    }
+  },
+  finalize: {
+    id: "cleanup_step_context", 
+    description: "Clean up after step completion",
+    handler: ({ context, data }) => {
+      // Complex ToolResult pattern
+      return {
+        data: "Cleanup complete",
+        success: true,
+        contextUpdate: { lastCleanup: new Date() }
+      };
     }
   }
 }
@@ -805,6 +922,130 @@ interface SessionData {
 }
 ```
 
+### Batch Execution Types
+
+Types for multi-step batch execution:
+
+```typescript
+/**
+ * Reason why batch execution stopped
+ */
+type StoppedReason =
+  | 'needs_input'      // Step requires uncollected data
+  | 'end_route'        // Reached END_ROUTE
+  | 'route_complete'   // All Steps processed
+  | 'prepare_error'    // Error in prepare hook
+  | 'llm_error'        // Error during LLM call
+  | 'validation_error' // Error validating collected data
+  | 'finalize_error';  // Error in finalize hook (non-fatal)
+
+/**
+ * Result of batch determination - which steps can execute together
+ */
+interface BatchResult<TContext = unknown, TData = unknown> {
+  /** Steps included in this batch */
+  steps: StepOptions<TContext, TData>[];
+  /** Why the batch stopped */
+  stoppedReason: StoppedReason;
+  /** The Step that caused the stop (if applicable) */
+  stoppedAtStep?: StepOptions<TContext, TData>;
+}
+
+/**
+ * Result of executing a batch of steps
+ */
+interface BatchExecutionResult<TData = unknown> {
+  /** The generated message */
+  message: string;
+  /** Updated session state */
+  session: SessionState<TData>;
+  /** Steps that were executed */
+  executedSteps: StepRef[];
+  /** Why execution stopped */
+  stoppedReason: StoppedReason;
+  /** Collected data from the batch */
+  collectedData?: Partial<TData>;
+  /** Any errors that occurred */
+  error?: BatchExecutionError;
+}
+
+/**
+ * Error details for batch execution failures
+ */
+interface BatchExecutionError {
+  /** Type of error that occurred */
+  type: 'pre_extraction' | 'skipif_evaluation' | 'prepare_hook' | 
+        'llm_call' | 'data_validation' | 'finalize_hook';
+  /** Error message */
+  message: string;
+  /** Step where error occurred (if applicable) */
+  stepId?: string;
+  /** Additional error details */
+  details?: unknown;
+}
+
+/**
+ * Event emitted during batch execution for debugging
+ */
+interface BatchExecutionEvent {
+  /** Type of batch execution event */
+  type: 'batch_start' | 'step_included' | 'step_skipped' | 'batch_stop' | 'batch_complete';
+  /** Timestamp when the event occurred */
+  timestamp: Date;
+  /** Event-specific details */
+  details: {
+    stepId?: string;
+    reason?: string;
+    batchSize?: number;
+    stoppedReason?: StoppedReason;
+    timing?: BatchExecutionTiming;
+  };
+}
+
+/**
+ * Timing information for batch execution phases
+ */
+interface BatchExecutionTiming {
+  /** Total batch execution time in milliseconds */
+  totalMs: number;
+  /** Time spent in batch determination phase */
+  determinationMs?: number;
+  /** Time spent executing prepare hooks */
+  prepareHooksMs?: number;
+  /** Time spent in LLM call */
+  llmCallMs?: number;
+  /** Time spent collecting data */
+  dataCollectionMs?: number;
+  /** Time spent executing finalize hooks */
+  finalizeHooksMs?: number;
+}
+```
+
+### Enhanced AgentResponse
+
+The AgentResponse interface includes batch execution fields:
+
+```typescript
+interface AgentResponse<TData = unknown> {
+  /** The generated message */
+  message: string;
+  /** Updated session state */
+  session?: SessionState<TData>;
+  /** Tool calls made during response */
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  /** Whether the route is complete */
+  isRouteComplete?: boolean;
+  
+  // Multi-step execution fields
+  /** Steps executed in this response */
+  executedSteps?: StepRef[];
+  /** Why execution stopped */
+  stoppedReason?: StoppedReason;
+  /** Error information if execution failed */
+  error?: BatchExecutionError;
+}
+```
+
 ### Tool Types
 
 ```typescript