@falai/agent 0.9.0 → 1.0.0

package/docs/README.md

@@ -8,8 +8,9 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 - 🎯 **Schema-First Data Collection**: Type-safe, structured data extraction from natural conversations
 - 🔀 **Route DSL**: Fluent, composable API for building complex multi-step conversation flows
 - 🏗️ **Type-Safe Context**: Generic context management with lifecycle hooks and dynamic providers
-- 🔄 **Streaming & Tools**: Real-time streaming responses with dynamic tool execution
+- 🔄 **Streaming & Tools**: Real-time streaming responses with dynamic tool execution using unified Tool interface
 - 💾 **Comprehensive Persistence**: Database-agnostic session and message storage across multiple adapters
+- 🛠️ **Unified Tool System**: Simplified tool creation with flexible return types and powerful pattern helpers
 
 ## 📖 Documentation Structure
 
@@ -54,6 +55,11 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 - **[Session Storage](./core/persistence/session-storage.md)** - Session persistence patterns
 - **[Database Adapters](./core/persistence/adapters.md)** - Built-in adapter configurations
 
+#### Error Handling
+
+- **[Error Handling](./core/error-handling.md)** - Comprehensive error handling patterns and recovery strategies
+- **[Error Handling Patterns](./guides/error-handling-patterns.md)** - Practical patterns for streaming, routing, and data sync errors
+
 ### 🚀 Advanced Guides
 
 - **[Building Agents](./guides/building-agents/)** - Complete agent construction patterns
@@ -94,6 +100,7 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 - **AI Integration**: [Providers](./core/ai-integration/providers.md) | [Prompts](./core/ai-integration/prompt-composition.md) | [Responses](./core/ai-integration/response-processing.md)
 - **Tools & Execution**: [Tool Definition](./core/tools/tool-definition.md) | [Tool Execution](./core/tools/tool-execution.md) | [Tool Scoping](./core/tools/tool-scoping.md)
 - **Persistence**: [Session Storage](./core/persistence/session-storage.md) | [Adapters](./core/persistence/adapters.md)
+- **Error Handling**: [Core Error Handling](./core/error-handling.md) | [Error Patterns](./guides/error-handling-patterns.md)
 - **Advanced**: [Building Agents](./guides/building-agents/) | [Patterns](./guides/advanced-patterns/) | [Migration](./guides/migration/) | [API Reference](./api/)
 
 ## 💡 Examples by Domain
@@ -129,10 +136,10 @@ Check out the [`examples/`](../examples/) directory for complete, runnable examp
 
 ### 🔧 Tools & Execution
 
-- **[Basic Tools](../examples/tools/basic-tools.ts)** - Simple tool creation and execution
-- **[Data Enrichment Tools](../examples/tools/data-enrichment-tools.ts)** - Tools that modify collected data
-- **[Context Updating Tools](../examples/tools/context-updating-tools.ts)** - Tools that modify agent context
-- **[Domain Scoped Tools](../examples/tools/domain-scoped-tools.ts)** - Tool security and access control
+- **[Basic Tools](../examples/tools/basic-tools.ts)** - Unified Tool interface with simple return values
+- **[Data Enrichment Tools](../examples/tools/data-enrichment-tools.ts)** - Pattern helpers for data modification
+- **[Context Updating Tools](../examples/tools/context-updating-tools.ts)** - Advanced ToolResult patterns with context updates
+- **[Domain Scoped Tools](../examples/tools/domain-scoped-tools.ts)** - Tool registry and scoping with agent.tool.register()
 
 ### 💾 Persistence
 

package/docs/api/README.md

@@ -15,6 +15,106 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
 
 ---
 
+## ConditionTemplate System
+
+### `ConditionTemplate<TContext, TData>`
+
+**NEW:** Enhanced condition type that supports flexible routing logic with both AI context and programmatic evaluation.
+
+```typescript
+type ConditionTemplate<TContext = unknown, TData = unknown> =
+  | string  // AI context only - provides context to AI for routing decisions
+  | ((params: TemplateContext<TContext, TData>) => boolean | Promise<boolean>) // Programmatic evaluation
+  | ConditionTemplate<TContext, TData>[]; // Array of either type
+```
+
+**Key Features:**
+
+- **String conditions**: Provide AI context for routing decisions (e.g., `"user wants to book a flight"`)
+- **Function conditions**: Execute programmatic logic returning boolean (e.g., `(ctx) => ctx.data?.isLoggedIn === true`)
+- **Array conditions**: Combine multiple conditions with logical operators
+- **Hybrid approach**: Mix strings and functions for optimal flexibility
+
+#### Evaluation Logic
+
+**For `when` conditions (AND logic):**
+- **Functions**: All must return `true` for condition to pass
+- **Strings**: Ignored in programmatic evaluation, used for AI context
+- **Arrays**: All functions must return `true`
+
+**For `skipIf` conditions (OR logic):**
+- **Functions**: Any returning `true` causes skip
+- **Strings**: Ignored in programmatic evaluation, used for AI context  
+- **Arrays**: Any function returning `true` causes skip
+
+#### Usage Examples
+
+```typescript
+// String-only condition (AI context)
+when: "User wants to make a reservation"
+
+// Function-only condition (programmatic)
+when: (ctx) => ctx.data?.userType === 'premium'
+
+// Mixed array condition (hybrid approach)
+when: [
+  "User is asking for help", // AI context
+  (ctx) => ctx.data?.isLoggedIn === true // Programmatic check
+]
+
+// Route skipIf with OR logic
+skipIf: [
+  "System is under maintenance", // AI context
+  (ctx) => ctx.data?.maintenanceMode === true // Programmatic check
+]
+```
+
+### `ConditionEvaluator<TContext, TData>`
+
+**NEW:** Utility class for evaluating ConditionTemplate instances with consistent logic across the framework.
+
+#### Constructor
+
+```typescript
+new ConditionEvaluator<TContext, TData>(templateContext: TemplateContext<TContext, TData>)
+```
+
+#### Methods
+
+##### `evaluateCondition(condition, logic?): Promise<ConditionEvaluationResult>`
+
+Evaluates a ConditionTemplate and returns detailed results.
+
+**Parameters:**
+- `condition`: ConditionTemplate to evaluate
+- `logic`: 'AND' | 'OR' - logical operator for arrays (default: 'AND')
+
+**Returns:**
+```typescript
+interface ConditionEvaluationResult {
+  programmaticResult: boolean; // Result of function evaluations only
+  aiContextStrings: string[]; // String values for AI context
+  hasProgrammaticConditions: boolean; // Whether any functions were evaluated
+}
+```
+
+**Example:**
+
+```typescript
+const evaluator = new ConditionEvaluator(templateContext);
+
+const result = await evaluator.evaluateCondition([
+  "User needs premium support", // AI context
+  (ctx) => ctx.data?.userType === 'premium' // Programmatic
+]);
+
+console.log(result.programmaticResult); // true/false from function
+console.log(result.aiContextStrings); // ["User needs premium support"]
+console.log(result.hasProgrammaticConditions); // true
+```
+
+---
+
 ## Core Classes
 
 ### `Agent<TContext, TData>`
@@ -74,6 +174,72 @@ Adds a domain glossary term. Returns `this` for chaining.
 
 Adds a behavioral guideline. Returns `this` for chaining.
 
+##### `addTool(definition: Tool<TContext, TData, TResult>): this`
+
+Creates and adds a tool to agent scope using the unified Tool interface. Returns `this` for chaining.
+
+```typescript
+// Simple return value approach
+agent.addTool({
+  id: "weather_check",
+  description: "Get current weather",
+  parameters: {
+    type: "object",
+    properties: {
+      location: { type: "string", description: "City name" }
+    },
+    required: ["location"]
+  },
+  handler: async ({ context, data }, args) => {
+    const weather = await weatherAPI.get(args.location);
+    return `Weather in ${args.location}: ${weather.condition}`;
+  }
+});
+
+// Advanced ToolResult pattern
+agent.addTool({
+  id: "user_lookup",
+  description: "Look up user information",
+  handler: async ({ context, data }, args) => {
+    const user = await userAPI.find(args.userId);
+    return {
+      data: `Found user: ${user.name}`,
+      success: true,
+      contextUpdate: { currentUser: user },
+      dataUpdate: { userName: user.name }
+    };
+  }
+});
+```
+
+##### `tool: ToolManager<TContext, TData>`
+
+Access to the ToolManager instance for advanced tool operations.
+
+```typescript
+// Register tools for ID-based reference
+agent.tool.register({
+  id: "reusable_search",
+  description: "Search across data sources",
+  handler: async ({ context, data }, args) => "Search results"
+});
+
+// Create tools without adding to scope
+const customTool = agent.tool.create({
+  id: "standalone_tool",
+  handler: async () => "Custom result"
+});
+
+// Use pattern helpers
+const enrichmentTool = agent.tool.createDataEnrichment({
+  id: "enrich_profile",
+  fields: ['name', 'email'],
+  enricher: async (context, data) => ({
+    displayName: `${data.name} <${data.email}>`
+  })
+});
+```
+
 ##### `respond(input: RespondInput<TContext>): Promise<RespondOutput>`
 
 Generates an AI response with session step management, tool execution, data extraction, and intelligent routing.
@@ -757,7 +923,8 @@ interface RouteOptions<TData = unknown> {
   description?: string;     // Route description
   identity?: string;        // Optional identity prompt defining the agent's role and persona for this route
   personality?: Template;   // Optional personality prompt defining the agent's communication style for this route
-  conditions?: string[];    // Conditions that activate this route
+  when?: ConditionTemplate; // NEW: Conditions that activate this route (replaces conditions)
+  skipIf?: ConditionTemplate; // NEW: Conditions that exclude this route from consideration
   guidelines?: Guideline[]; // Initial guidelines for this route
   terms?: Term[];          // Initial terms for the route's domain glossary
   rules?: string[];         // Absolute rules the agent MUST follow in this route
@@ -869,7 +1036,7 @@ console.log(description);
 // Route: Book Flight
 // ID: route_book_flight
 // Description: N/A
-// Conditions: None
+// When: None
 //
 // Steps:
 //   - step_ask_destination: Ask where to fly
@@ -937,9 +1104,13 @@ Route title (readonly).
 
 Route description (readonly).
 
-##### `conditions: string[]`
+##### `when?: ConditionTemplate`
+
+**NEW:** Conditions that trigger this route (readonly). Can be a string, function, or array of either.
 
-Conditions that trigger this route (readonly).
+##### `skipIf?: ConditionTemplate`
+
+**NEW:** Conditions that exclude this route from consideration (readonly). Can be a string, function, or array of either.
 
 ##### `initialStep: Step`
 
@@ -957,7 +1128,7 @@ Represents a step within a conversation route.
 
 #### Methods
 
-##### `nextStep(spec: StepOptions): StepResult`
+##### `nextStep(spec: StepOptions): Step`
 
 Creates a transition from this step and returns a chainable result.
 
@@ -972,20 +1143,25 @@ interface StepOptions<TData = unknown> {
   // NEW: Data extraction fields for this step
   collect?: string[];
 
-  // NEW: Code-based condition to skip this step
-  skipIf?: (data: Partial<TData>) => boolean;
+  // ENHANCED: Flexible condition to determine when this step should be active
+  when?: ConditionTemplate<TContext, TData>;
+
+  // ENHANCED: Flexible condition to skip this step
+  skipIf?: ConditionTemplate<TContext, TData>;
 
   // NEW: Prerequisites that must be met to enter this step
   requires?: string[];
-
-  // Optional: AI-evaluated text condition for this transition
-  condition?: string;
 }
 
-interface StepResult<TData = unknown> {
+interface Step<TContext = unknown, TData = unknown> {
   id: string; // Step identifier
   routeId: string; // Route identifier
-  nextStep: (spec: StepOptions<TData>) => StepResult<TData>;
+  nextStep: (spec: StepOptions<TContext, TData>) => Step<TContext, TData>;
+  description?: string; // Step description
+  collect?: (keyof TData)[]; // Fields to collect in this step
+  when?: ConditionTemplate<TContext, TData>; // ENHANCED: Flexible condition for step activation
+  skipIf?: ConditionTemplate<TContext, TData>; // ENHANCED: Flexible condition to skip step
+  requires?: (keyof TData)[]; // Required data prerequisites
 }
 ```
 
@@ -993,7 +1169,7 @@ interface StepResult<TData = unknown> {
 
 - `spec`: The transition specification (see `StepOptions` above). Can include an optional `condition` property for AI-evaluated step selection guidance.
 
-**Returns:** A `StepResult` that includes the target step's reference (`id`, `routeId`) and a `nextStep` method for chaining additional transitions.
+**Returns:** A `Step` that includes the target step's reference (`id`, `routeId`) and a `nextStep` method for chaining additional transitions.
 
 **Example:**
 
@@ -1110,14 +1286,7 @@ if (step.hasRequires(session.data)) {
 }
 ```
 
-##### `asStepResult(): StepResult<TContext, TData>`
-
-Creates a transition result for this step that supports chaining.
 
-```typescript
-const result = step.asStepResult();
-// Returns StepResult with nextStep method for chaining
-```
 
 ##### `configure(config): this`
 
@@ -1167,6 +1336,109 @@ Step description (readonly).
 
 ---
 
+### `StepResult`
+
+Result interface returned by step transition methods that enables fluent chaining of conversation flows. Combines step reference with the ability to chain transitions and create branches.
+
+#### Interface
+
+```typescript
+interface StepResult<TContext = unknown, TData = unknown> extends StepRef {
+  /** Allow chaining transitions */
+  nextStep: (spec: StepOptions<TContext, TData>) => StepResult<TContext, TData>;
+  /** Create multiple branches from this step */
+  branch: (
+    branches: BranchSpec<TContext, TData>[]
+  ) => BranchResult<TContext, TData>;
+  /** Shortcut to end the current route */
+  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
+}
+```
+
+#### Methods
+
+##### `nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData>`
+
+Creates a transition from this step and returns a chainable result for building linear flows.
+
+**Example:**
+
+```typescript
+// Linear flow chaining
+const flow = route.initialStep
+  .nextStep({
+    prompt: "Ask for destination",
+    collect: ["destination"]
+  })
+  .nextStep({
+    prompt: "Ask for dates", 
+    collect: ["departureDate", "returnDate"]
+  })
+  .nextStep({
+    prompt: "Confirm booking details"
+  });
+```
+
+##### `branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>`
+
+Creates multiple conditional branches from this step for complex conversation flows.
+
+**Example:**
+
+```typescript
+// Branching flow
+const branches = askIssueType.branch([
+  {
+    name: "technical",
+    step: {
+      prompt: "Let me help with your technical issue",
+      when: "issue type is technical"
+    }
+  },
+  {
+    name: "billing", 
+    step: {
+      prompt: "I'll connect you with billing support",
+      when: "issue type is billing"
+    }
+  }
+]);
+
+// Continue each branch independently
+branches.technical.nextStep({ prompt: "What device are you using?" });
+branches.billing.nextStep({ prompt: "What's your account number?" });
+```
+
+##### `endRoute(options?: Omit<StepOptions<TContext, TData>, "step">): StepResult<TContext, TData>`
+
+Shortcut method to end the current route with optional completion configuration.
+
+**Example:**
+
+```typescript
+// Simple route completion
+askConfirmation.endRoute();
+
+// Route completion with final message
+askConfirmation.endRoute({
+  prompt: "Thank you! Your booking is confirmed."
+});
+```
+
+#### Properties
+
+Inherits all properties from `StepRef`:
+
+##### `id: string`
+
+Step identifier (readonly).
+
+##### `routeId: string`
+
+Route this step belongs to (readonly).
+
+---
+
 ---
 
 ## Tool Execution
@@ -1566,39 +1838,6 @@ Builds a fallback prompt when no routes are configured.
 
 ---
 
-### `ToolExecutor<TContext, TData>`
-
-Executes tools with context and security enforcement.
-
-#### Constructor
-
-```typescript
-new ToolExecutor<TContext, TData>();
-```
-
-#### Methods
-
-##### `executeTool(params): Promise<ToolExecutionResult>`
-
-Executes a single tool with domain security enforcement.
-
-**Parameters:**
-
-- `tool`: Tool reference to execute
-- `context`: Agent context
-- `updateContext`: Function to update context
-- `history`: Conversation history
-- `data`: Collected session data
-- `allowedDomains`: Array of allowed domain names
-
-**Returns:** Tool execution result with success status and data
-
-##### `executeTools(params): Promise<ToolExecutionResult[]>`
-
-Executes multiple tools in sequence, stopping on first failure.
-
----
-
 ### `Events`
 
 Utility functions for creating and adapting conversation events.
@@ -2364,9 +2603,9 @@ interface Term<TContext = unknown> {
 ### `Guideline`
 
 ```typescript
-interface Guideline<TContext = unknown> {
+interface Guideline<TContext = unknown, TData = unknown> {
   id?: string;
-  condition?: Template<TContext>;
+  condition?: ConditionTemplate<TContext, TData>; // ENHANCED: Flexible condition for guideline activation
   action: Template<TContext>;
   enabled?: boolean; // Default: true
   tags?: string[];
@@ -3016,4 +3255,4 @@ agent.createGuideline({
 
 ---
 
-**Made with ❤️ for the community**
+**Made with ❤️ for the community**