@falai/agent 0.3.0 → 0.3.11

package/docs/API_REFERENCE.md

@@ -40,9 +40,17 @@ Adds an agent capability. Returns `this` for chaining.
 
 Creates an observation for disambiguation.
 
-##### `addDomain<TName, TDomain>(name: TName, domainObject: TDomain): this`
+##### `addDomain<TName, TDomain>(name: TName, domainObject: TDomain): void`
 
-Registers a domain with tools/methods. Returns `this` for chaining.
+Registers a domain with tools/methods.
+
+##### `getDomainsForRoute(routeId: string): Record<string, Record<string, unknown>>`
+
+Gets allowed domains for a specific route by ID. Returns filtered domains based on route's `domains` property, or all domains if route has no restrictions.
+
+##### `getDomainsForRouteByTitle(routeTitle: string): Record<string, Record<string, unknown>>`
+
+Gets allowed domains for a specific route by title. Returns filtered domains based on route's `domains` property, or all domains if route has no restrictions.
 
 ##### `respond(input: RespondInput<TContext>): Promise<RespondOutput>`
 
@@ -101,6 +109,107 @@ if (response.route?.title === END_ROUTE) {
 }
 ```
 
+##### `respondStream(input: RespondInput<TContext>): AsyncGenerator<StreamChunk>`
+
+Generates an AI response as a real-time stream for better user experience. Provides the same structured output as `respond()` but delivers it incrementally.
+
+```typescript
+interface StreamChunk {
+  /** The incremental text delta */
+  delta: string;
+  /** Full accumulated text so far */
+  accumulated: string;
+  /** Whether this is the final chunk */
+  done: boolean;
+  /** Route chosen by the agent (only in final chunk) */
+  route?: { id: string; title: string };
+  /** Current state within the route (only in final chunk) */
+  state?: { id: string; description?: string };
+  /** Tool calls requested by the agent (only in final chunk) */
+  toolCalls?: Array<{
+    toolName: string;
+    arguments: Record<string, unknown>;
+  }>;
+}
+```
+
+**Key Features:**
+
+- 🌊 Real-time streaming for better perceived performance
+- 📊 Access to route, state, and tool information in final chunk
+- 🛑 Cancellable with AbortSignal
+- ✅ Supported by all providers (Anthropic, OpenAI, Gemini, OpenRouter)
+
+**Example:**
+
+```typescript
+// Basic streaming
+for await (const chunk of agent.respondStream({ history })) {
+  if (chunk.delta) {
+    // Display incremental text to user
+    process.stdout.write(chunk.delta);
+  }
+
+  if (chunk.done) {
+    console.log("\n✅ Complete!");
+    // Access final metadata
+    if (chunk.route) {
+      console.log("Route:", chunk.route.title);
+    }
+    if (chunk.toolCalls) {
+      console.log("Tool calls:", chunk.toolCalls.length);
+    }
+  }
+}
+```
+
+**With Cancellation:**
+
+```typescript
+const abortController = new AbortController();
+
+// Cancel after 5 seconds
+setTimeout(() => abortController.abort(), 5000);
+
+try {
+  for await (const chunk of agent.respondStream({
+    history,
+    signal: abortController.signal,
+  })) {
+    console.log(chunk.delta);
+  }
+} catch (error) {
+  if (error.name === "AbortError") {
+    console.log("Stream cancelled");
+  }
+}
+```
+
+**Collecting Full Response:**
+
+```typescript
+let fullMessage = "";
+let finalChunk;
+
+for await (const chunk of agent.respondStream({ history })) {
+  fullMessage += chunk.delta;
+  if (chunk.done) {
+    finalChunk = chunk;
+  }
+}
+
+// Save to database
+await db.agentMessages.create({
+  sessionId: session.id,
+  role: "agent",
+  content: fullMessage,
+  route: finalChunk.route?.title,
+  toolCalls: finalChunk.toolCalls || [],
+});
+```
+
+**See Also:** [streaming-agent.ts](../examples/streaming-agent.ts) for comprehensive examples.
+
 #### Properties
 
 ##### `name: string`
@@ -136,6 +245,9 @@ interface RouteOptions {
   description?: string;     // Route description
   conditions?: string[];    // Conditions that activate this route
   guidelines?: Guideline[]; // Initial guidelines for this route
+  domains?: string[];       // Domain names allowed in this route (undefined = all domains)
+  rules?: string[];         // Absolute rules the agent MUST follow in this route
+  prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do in this route
 }
 ```
 
@@ -151,6 +263,18 @@ Adds a guideline specific to this route. Returns `this` for chaining.
 
 Returns all guidelines for this route.
 
+##### `getDomains(): string[] | undefined`
+
+Returns allowed domain names for this route. Returns `undefined` if all domains are allowed, or an array of domain names if restricted.
+
+##### `getRules(): string[]`
+
+Returns the rules that must be followed in this route.
+
+##### `getProhibitions(): string[]`
+
+Returns the prohibitions that must never be done in this route.
+
 ##### `getRef(): RouteRef`
 
 Returns a reference to this route.
@@ -216,6 +340,7 @@ interface TransitionResult {
 **Example:**
 
 ```typescript
+// Approach 1: Step-by-step (ideal for complex flows with branching)
 const t0 = route.initialState.transitionTo({
   chatState: "Ask for user name",
 });
@@ -224,9 +349,30 @@ const t1 = t0.transitionTo({
   chatState: "Ask for email",
 });
 
+const t2 = t1.transitionTo({
+  chatState: "Confirm details",
+});
+
 // Access state properties
 console.log(t1.id); // State ID
 console.log(t1.routeId); // Route ID
+
+// Use saved references for branching
+t1.transitionTo(
+  { chatState: "Handle invalid email" },
+  "Email validation failed"
+);
+
+// Approach 2: Fluent chaining (elegant for linear flows)
+route.initialState
+  .transitionTo({ chatState: "Ask for user name" })
+  .transitionTo({ chatState: "Ask for email" })
+  .transitionTo({ chatState: "Confirm details" })
+  .transitionTo({ state: END_ROUTE });
+
+// Both approaches are equivalent - choose based on your needs:
+// - Use step-by-step for complex flows with conditional branches
+// - Use chaining for simple linear flows for conciseness
 ```
 
 ##### `addGuideline(guideline: Guideline): void`
@@ -289,6 +435,117 @@ Observation description (readonly).
 
 ---
 
+### `DomainRegistry`
+
+Registry for organizing agent tools and methods by domain.
+
+#### Methods
+
+##### `register<TDomain>(name: string, domain: TDomain): void`
+
+Registers a new domain with its tools/methods. Throws error if domain name already exists.
+
+##### `get<TDomain>(name: string): TDomain | undefined`
+
+Gets a registered domain by name. Returns `undefined` if not found.
+
+##### `has(name: string): boolean`
+
+Checks if a domain is registered.
+
+##### `all(): Record<string, Record<string, unknown>>`
+
+Returns all registered domains as a single object.
+
+##### `getFiltered(allowedNames?: string[]): Record<string, Record<string, unknown>>`
+
+Returns filtered domains by names. If `allowedNames` is `undefined`, returns all domains.
+
+**Example:**
+
+```typescript
+const registry = new DomainRegistry();
+
+registry.register("payment", {
+  processPayment: async (amount: number) => {
+    /* ... */
+  },
+});
+
+registry.register("shipping", {
+  calculateShipping: (zipCode: string) => {
+    /* ... */
+  },
+});
+
+// Get specific domains
+const filtered = registry.getFiltered(["payment"]); // Only payment domain
+
+// Get all domains
+const all = registry.getFiltered(); // payment + shipping
+```
+
+##### `getDomainNames(): string[]`
+
+Returns list of all registered domain names.
+
+---
+
+### `AnthropicProvider`
+
+AI provider implementation for Anthropic (Claude models).
+
+#### Constructor
+
+```typescript
+new AnthropicProvider(options: AnthropicProviderOptions)
+
+interface AnthropicProviderOptions {
+  apiKey: string;
+  model: string;               // Required: e.g., "claude-sonnet-4-5"
+  backupModels?: string[];     // Fallback models
+  config?: Partial<Omit<MessageCreateParamsNonStreaming, "model" | "messages" | "max_tokens">>;
+  retryConfig?: {
+    timeout?: number;          // Default: 60000ms
+    retries?: number;          // Default: 3
+  };
+}
+```
+
+**Note:** `model` is required for AnthropicProvider. Available models include:
+
+- `claude-sonnet-4-5` - Latest Claude Sonnet 4.5 (most capable)
+- `claude-opus-4-1` - Claude Opus 4.1 (powerful for complex tasks)
+- `claude-sonnet-4-0` - Claude Sonnet 4.0 (stable, production-ready)
+
+#### Methods
+
+##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
+
+Generates a message with retry logic and backup models using Anthropic's API.
+
+**Example:**
+
+```typescript
+import { AnthropicProvider } from "@falai/agent";
+
+const provider = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-5",
+  backupModels: ["claude-opus-4-1", "claude-sonnet-4-0"],
+  config: {
+    temperature: 0.7,
+    top_p: 0.9,
+  },
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
+```
+
+---
+
 ### `GeminiProvider`
 
 AI provider implementation for Google Gemini.
@@ -317,6 +574,104 @@ Generates a message with retry logic and backup models.
 
 ---
 
+### `OpenAIProvider`
+
+AI provider implementation for OpenAI (GPT models).
+
+#### Constructor
+
+```typescript
+new OpenAIProvider(options: OpenAIProviderOptions)
+
+interface OpenAIProviderOptions {
+  apiKey: string;
+  model: string;               // Required: e.g., "gpt-4o", "gpt-5"
+  backupModels?: string[];     // Fallback models
+  retryConfig?: {
+    timeout?: number;          // Default: 60000ms
+    retries?: number;          // Default: 3
+  };
+}
+```
+
+**Note:** Unlike GeminiProvider, `model` is required for OpenAIProvider. Choose from available OpenAI models like "gpt-4o", "gpt-5", "gpt-4-turbo", etc.
+
+#### Methods
+
+##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
+
+Generates a message with retry logic and backup models using OpenAI's API.
+
+**Example:**
+
+```typescript
+import { OpenAIProvider } from "@falai/agent";
+
+const provider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5",
+  backupModels: ["gpt-4o", "gpt-4-turbo"],
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
+```
+
+---
+
+### `OpenRouterProvider`
+
+AI provider implementation for OpenRouter (access to 200+ models).
+
+#### Constructor
+
+```typescript
+new OpenRouterProvider(options: OpenRouterProviderOptions)
+
+interface OpenRouterProviderOptions {
+  apiKey: string;
+  model: string;               // Required: e.g., "openai/gpt-5", "anthropic/claude-sonnet-4-5"
+  backupModels?: string[];     // Fallback models
+  siteUrl?: string;            // Optional: your app URL for OpenRouter rankings
+  siteName?: string;           // Optional: your app name for OpenRouter rankings
+  retryConfig?: {
+    timeout?: number;          // Default: 60000ms
+    retries?: number;          // Default: 3
+  };
+}
+```
+
+**Note:** OpenRouter provides access to models from multiple providers. Model names follow the format `provider/model-name` (e.g., "openai/gpt-5", "anthropic/claude-sonnet-4-5", "google/gemini-pro").
+
+#### Methods
+
+##### `generateMessage<TContext>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>`
+
+Generates a message with retry logic and backup models using OpenRouter's API.
+
+**Example:**
+
+```typescript
+import { OpenRouterProvider } from "@falai/agent";
+
+const provider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "openai/gpt-5",
+  backupModels: ["anthropic/claude-sonnet-4-5", "google/gemini-pro"],
+  siteUrl: "https://yourapp.com",
+  siteName: "Your App Name",
+  retryConfig: {
+    timeout: 60000,
+    retries: 3,
+  },
+});
+```
+
+**See Also:** [Providers Guide](./PROVIDERS.md) for detailed provider comparison and configuration examples.
+
+---
+
 ### `PromptBuilder`
 
 Constructs prompts for AI generation.