@falai/agent 0.9.0-alpha-2 → 0.9.2

package/docs/api/README.md

@@ -74,10 +74,78 @@ 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.
 
+**Note:** This method now delegates to the internal `ResponseModal` class for improved architecture and maintainability.
+
 **Enhanced Response Pipeline:**
 
 1. **Tool Execution** - Execute tools if current step has `tool` (enriches context before AI response)
@@ -454,6 +522,8 @@ See also: [Custom Database Integration Example](../examples/custom-database-pers
 
 Generates an AI response as a real-time stream for better user experience. Provides the same structured output as `respond()` but delivers it incrementally.
 
+**Note:** This method now delegates to the internal `ResponseModal` class for improved architecture and maintainability.
+
 ```typescript
 interface StreamChunk {
   /** The incremental text delta */
@@ -515,6 +585,68 @@ for await (const chunk of agent.respondStream({ history, session })) {
 }
 ```
 
+##### `stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>`
+
+**NEW:** Modern streaming API that provides a simple interface similar to `chat()` but returns a stream. This is the recommended way to implement streaming responses.
+
+```typescript
+interface StreamOptions<TContext = unknown> {
+  contextOverride?: Partial<TContext>;
+  signal?: AbortSignal;
+  history?: History; // Optional: override session history
+}
+```
+
+**Key Features:**
+
+- 🎯 **Simple Interface**: Just `agent.stream("message")` - no complex parameters
+- 🔄 **Automatic Session Management**: Handles conversation history automatically
+- 🌊 **Real-time Streaming**: Same performance as `respondStream()` but easier to use
+- 🛑 **Cancellable**: Supports AbortSignal for cancellation
+
+**Example:**
+
+```typescript
+// Simple streaming - automatically manages session history
+for await (const chunk of agent.stream("Hello, how are you?")) {
+  if (chunk.delta) {
+    process.stdout.write(chunk.delta);
+  }
+  
+  if (chunk.done) {
+    console.log("\n✅ Stream complete!");
+    // Session history is automatically updated
+  }
+}
+
+// With cancellation
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000); // Cancel after 5s
+
+for await (const chunk of agent.stream("Tell me a long story", {
+  signal: controller.signal
+})) {
+  process.stdout.write(chunk.delta);
+}
+```
+
+**Migration from `respondStream()`:**
+
+```typescript
+// Old way (still supported)
+for await (const chunk of agent.respondStream({
+  history: agent.session.getHistory(),
+  session: await agent.session.getOrCreate()
+})) {
+  // Handle chunk
+}
+
+// New way (recommended)
+for await (const chunk of agent.stream("Your message")) {
+  // Handle chunk - session management is automatic
+}
+```
+
 **With Cancellation:**
 
 ```typescript
@@ -582,6 +714,100 @@ Agent's identity template (readonly).
 
 ---
 
+### `ResponseModal<TContext, TData>`
+
+**NEW:** Internal class that handles all response generation logic for the Agent. This class centralizes response processing, provides unified streaming and non-streaming APIs, and improves maintainability.
+
+**Note:** This class is primarily used internally by the Agent class. Most users should use the Agent's response methods (`respond`, `respondStream`, `stream`, `chat`) rather than accessing ResponseModal directly.
+
+#### Constructor
+
+```typescript
+new ResponseModal<TContext, TData>(
+  agent: Agent<TContext, TData>,
+  options?: ResponseModalOptions
+)
+
+interface ResponseModalOptions {
+  /** Maximum number of tool loops allowed during response generation */
+  maxToolLoops?: number;
+  /** Enable automatic session saving after response generation */
+  enableAutoSave?: boolean;
+  /** Enable debug mode for detailed logging */
+  debugMode?: boolean;
+}
+```
+
+#### Methods
+
+##### `respond(params: RespondParams<TContext, TData>): Promise<AgentResponse<TData>>`
+
+Generates a non-streaming response using unified logic. This method consolidates all response generation logic including routing, tool execution, and data collection.
+
+##### `respondStream(params: RespondParams<TContext, TData>): AsyncGenerator<AgentResponseStreamChunk<TData>>`
+
+Generates a streaming response using unified logic. Provides the same functionality as `respond()` but delivers results incrementally.
+
+##### `stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>`
+
+Modern streaming API with automatic session management. This is the recommended way to implement streaming responses.
+
+```typescript
+// Simple usage
+for await (const chunk of responseModal.stream("Hello")) {
+  console.log(chunk.delta);
+}
+
+// With options
+for await (const chunk of responseModal.stream("Hello", {
+  contextOverride: { userId: "123" },
+  signal: abortController.signal
+})) {
+  console.log(chunk.delta);
+}
+```
+
+##### `generate(message?: string, options?: GenerateOptions<TContext>): Promise<AgentResponse<TData>>`
+
+Modern non-streaming API equivalent to `chat()` but more explicit. Provides automatic session management for non-streaming responses.
+
+```typescript
+// Simple usage
+const response = await responseModal.generate("Hello");
+console.log(response.message);
+
+// With options
+const response = await responseModal.generate("Hello", {
+  contextOverride: { userId: "123" }
+});
+```
+
+#### Error Handling
+
+ResponseModal includes comprehensive error handling with the `ResponseGenerationError` class:
+
+```typescript
+try {
+  const response = await responseModal.respond(params);
+} catch (error) {
+  if (ResponseGenerationError.isResponseGenerationError(error)) {
+    console.log("Response generation failed:", error.message);
+    console.log("Phase:", error.details?.phase);
+    console.log("Original error:", error.details?.originalError);
+  }
+}
+```
+
+#### Architecture Benefits
+
+- **Separation of Concerns**: Agent focuses on configuration and orchestration, ResponseModal handles response generation
+- **Unified Logic**: Both streaming and non-streaming responses use the same underlying logic
+- **Modern APIs**: Provides simple `stream()` and `generate()` methods alongside legacy compatibility
+- **Error Handling**: Comprehensive error handling with detailed context
+- **Performance**: Optimized response pipeline with minimal duplication
+
+---
+
 ### `Route`
 
 Represents a conversation flow with steps and transitions.
@@ -797,7 +1023,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.
 
@@ -822,10 +1048,14 @@ interface StepOptions<TData = unknown> {
   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
+  skipIf?: (data: Partial<TData>) => boolean; // Skip condition function
+  requires?: (keyof TData)[]; // Required data prerequisites
 }
 ```
 
@@ -833,7 +1063,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:**
 
@@ -950,14 +1180,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`
 
@@ -1406,39 +1629,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.
@@ -2856,4 +3046,4 @@ agent.createGuideline({
 
 ---
 
-**Made with ❤️ for the community**
+**Made with ❤️ for the community**

package/docs/api/overview.md

@@ -6,12 +6,13 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
 
 - [Core Classes](#core-classes)
   - [Agent](#agent)
+  - [ResponseModal](#responsemodal)
   - [Route](#route)
   - [Step](#step)
   - [RoutingEngine](#routingengine)
   - [ResponseEngine](#responseengine)
   - [PromptComposer](#promptcomposer)
-  - [ToolExecutor](#toolexecutor)
+
 - [AI Providers](#ai-providers)
 - [Persistence Adapters](#persistence-adapters)
 - [Types & Interfaces](#types--interfaces)
@@ -117,14 +118,76 @@ respondStream(params: {
 }>
 ```
 
-Generates a streaming response with real-time updates.
+Generates a streaming response with real-time updates. **Note:** Now delegates to internal ResponseModal class.
+
+```typescript
+stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>
+```
+
+**NEW:** Modern streaming API with automatic session management. Recommended for new implementations.
+
+```typescript
+// Simple streaming
+for await (const chunk of agent.stream("Hello")) {
+  console.log(chunk.delta);
+}
+```
 
 ##### 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
@@ -168,6 +231,57 @@ hasPersistence(): boolean
 
 ---
 
+### ResponseModal
+
+**NEW:** Internal class that centralizes all response generation logic for improved architecture and maintainability.
+
+#### Constructor
+
+```typescript
+new ResponseModal<TContext = unknown, TData = unknown>(
+  agent: Agent<TContext, TData>,
+  options?: ResponseModalOptions
+)
+```
+
+#### Methods
+
+##### Modern APIs (Recommended)
+
+```typescript
+stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>
+generate(message?: string, options?: GenerateOptions<TContext>): Promise<AgentResponse<TData>>
+```
+
+Modern streaming and non-streaming APIs with automatic session management.
+
+##### Legacy APIs (Backward Compatible)
+
+```typescript
+respond(params: RespondParams<TContext, TData>): Promise<AgentResponse<TData>>
+respondStream(params: RespondParams<TContext, TData>): AsyncGenerator<AgentResponseStreamChunk<TData>>
+```
+
+Legacy APIs that maintain full backward compatibility with existing code.
+
+##### Error Handling
+
+```typescript
+ResponseGenerationError: Error class for response-specific errors
+```
+
+Comprehensive error handling with detailed context and phase information.
+
+#### Key Features
+
+- **Unified Logic**: Both streaming and non-streaming use the same underlying logic
+- **Modern APIs**: Simple `stream()` and `generate()` methods for new code
+- **Backward Compatibility**: Existing `respond()` and `respondStream()` methods work unchanged
+- **Error Handling**: Detailed error context with phase and original error information
+- **Performance**: Optimized response pipeline with minimal code duplication
+
+---
+
 ### Route
 
 Represents a conversational journey with required fields specification and steps that collect data into the agent-level schema.
@@ -236,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
@@ -282,9 +394,9 @@ configure(config: Partial<StepOptions<TContext, TData>>): this
 ##### Transitions
 
 ```typescript
-nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData>
+nextStep(spec: StepOptions<TContext, TData>): Step<TContext, TData>
 branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>
-endRoute(options?: Omit<StepOptions<TContext, TData>, 'step'>): StepResult<TContext, TData>
+endRoute(options?: Omit<StepOptions<TContext, TData>, 'step'>): Step<TContext, TData>
 ```
 
 ##### Validation
@@ -306,7 +418,6 @@ getTransitions(): Step<TContext, TData>[]
 
 ```typescript
 getRef(): StepRef
-asStepResult(): StepResult<TContext, TData>
 ```
 
 ---
@@ -440,23 +551,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>
-```
 
 ---
 
@@ -691,21 +786,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() }
+      };
     }
   }
 }