@falai/agent 0.3.0 → 0.3.11

package/src/core/PromptBuilder.ts

@@ -26,6 +26,7 @@ export enum BuiltInSection {
   OBSERVATIONS = "observations",
   CAPABILITIES = "capabilities",
   ACTIVE_ROUTES = "active_routes",
+  DOMAINS = "domains",
 }
 
 /**
@@ -431,7 +432,14 @@ When you detect any of these situations, consider which route would be most appr
    * Add active routes information
    */
   addActiveRoutes(
-    routes: Array<{ title: string; description?: string; conditions: string[] }>
+    routes: Array<{
+      title: string;
+      description?: string;
+      conditions: string[];
+      domains?: string[];
+      rules?: string[];
+      prohibitions?: string[];
+    }>
   ): this {
     if (routes.length > 0) {
       const routesString = routes
@@ -441,7 +449,29 @@ When you detect any of these situations, consider which route would be most appr
               ? `\n  Triggered when: ${route.conditions.join(" OR ")}`
               : "";
           const desc = route.description ? `\n  ${route.description}` : "";
-          return `${i + 1}) ${route.title}${desc}${conditions}`;
+          
+          let domainInfo = "";
+          if (route.domains !== undefined) {
+            if (route.domains.length === 0) {
+              domainInfo = "\n  Available tools: None (conversation only)";
+            } else {
+              domainInfo = `\n  Available tools: ${route.domains.join(", ")}`;
+            }
+          }
+
+          let rulesInfo = "";
+          if (route.rules && route.rules.length > 0) {
+            const rulesList = route.rules.map((r, idx) => `${idx + 1}. ${r}`).join("; ");
+            rulesInfo = `\n  RULES: ${rulesList}`;
+          }
+
+          let prohibitionsInfo = "";
+          if (route.prohibitions && route.prohibitions.length > 0) {
+            const prohibitionsList = route.prohibitions.map((p, idx) => `${idx + 1}. ${p}`).join("; ");
+            prohibitionsInfo = `\n  PROHIBITIONS: ${prohibitionsList}`;
+          }
+
+          return `${i + 1}) ${route.title}${desc}${conditions}${domainInfo}${rulesInfo}${prohibitionsInfo}`;
         })
         .join("\n\n");
 
@@ -452,7 +482,11 @@ When you detect any of these situations, consider which route would be most appr
 {routes_string}
 ###
 
-These routes represent different paths the conversation can take. Choose the most appropriate route based on the user's needs.`,
+These routes represent different paths the conversation can take. Choose the most appropriate route based on the user's needs.
+IMPORTANT: 
+- If a route specifies available tools, you can ONLY call tools from those domains when following that route.
+- If a route has RULES, you MUST follow them when you choose that route.
+- If a route has PROHIBITIONS, you MUST NEVER do those things when you choose that route.`,
         { routes_string: routesString },
         SectionStatus.ACTIVE
       );
@@ -460,6 +494,39 @@ These routes represent different paths the conversation can take. Choose the mos
     return this;
   }
 
+  /**
+   * Add domains (tools) information
+   */
+  addDomains(
+    domains: Record<string, Record<string, unknown>>
+  ): this {
+    const domainNames = Object.keys(domains);
+    if (domainNames.length > 0) {
+      const domainsString = domainNames
+        .map((name, i) => {
+          const toolNames = Object.keys(domains[name]);
+          const tools = toolNames.join(", ");
+          return `${i + 1}) Domain "${name}": ${tools}`;
+        })
+        .join("\n");
+
+      this.addSection(
+        BuiltInSection.DOMAINS,
+        `Available tool domains:
+###
+{domains_string}
+###
+
+These are the tool domains registered in the system. Each domain contains specific tools/methods.
+When calling tools, use the format: domain.toolName (e.g., "payment.processPayment").`,
+        { domains_string: domainsString },
+        SectionStatus.ACTIVE
+      );
+    }
+    return this;
+  }
+
+
   /**
    * Add JSON response schema instructions
    */

package/src/core/Route.ts

@@ -16,6 +16,9 @@ export class Route<TContext = unknown> {
   public readonly title: string;
   public readonly description?: string;
   public readonly conditions: string[];
+  public readonly domains?: string[];
+  public readonly rules: string[];
+  public readonly prohibitions: string[];
   public readonly initialState: State<TContext>;
   private guidelines: Guideline[] = [];
 
@@ -25,6 +28,9 @@ export class Route<TContext = unknown> {
     this.title = options.title;
     this.description = options.description;
     this.conditions = options.conditions || [];
+    this.domains = options.domains;
+    this.rules = options.rules || ([] as string[]);
+    this.prohibitions = options.prohibitions || ([] as string[]);
     this.initialState = new State<TContext>(this.id, "Initial state");
 
     // Initialize guidelines from options
@@ -54,6 +60,28 @@ export class Route<TContext = unknown> {
     return [...this.guidelines];
   }
 
+  /**
+   * Get allowed domain names for this route
+   * @returns Array of domain names, or undefined if all domains are allowed
+   */
+  getDomains(): string[] | undefined {
+    return this.domains ? [...this.domains] : undefined;
+  }
+
+  /**
+   * Get rules for this route
+   */
+  getRules(): string[] {
+    return [...this.rules];
+  }
+
+  /**
+   * Get prohibitions for this route
+   */
+  getProhibitions(): string[] {
+    return [...this.prohibitions];
+  }
+
   /**
    * Get route reference
    */

package/src/index.ts

@@ -24,6 +24,8 @@ export { OpenAIProvider } from "./providers/OpenAIProvider";
 export type { OpenAIProviderOptions } from "./providers/OpenAIProvider";
 export { OpenRouterProvider } from "./providers/OpenRouterProvider";
 export type { OpenRouterProviderOptions } from "./providers/OpenRouterProvider";
+export { AnthropicProvider } from "./providers/AnthropicProvider";
+export type { AnthropicProviderOptions } from "./providers/AnthropicProvider";
 
 // Constants
 export { END_ROUTE } from "./constants";

package/src/providers/AnthropicProvider.ts

@@ -0,0 +1,467 @@
+/**
+ * Anthropic (Claude) provider implementation with retry and backup models
+ */
+
+import Anthropic from "@anthropic-ai/sdk";
+import type { MessageCreateParamsNonStreaming } from "@anthropic-ai/sdk/resources/messages";
+
+import type {
+  AiProvider,
+  GenerateMessageInput,
+  GenerateMessageOutput,
+  GenerateMessageStreamChunk,
+  AgentStructuredResponse,
+} from "../types/ai";
+import { withTimeoutAndRetry } from "../utils/retry";
+
+const DEFAULT_RETRY_CONFIG = {
+  timeout: 60000,
+  retries: 3,
+};
+
+/**
+ * Configuration options for Anthropic provider
+ * Uses types from @anthropic-ai/sdk package
+ */
+export interface AnthropicProviderOptions {
+  /** Anthropic API key */
+  apiKey: string;
+  /** Model to use (required) - e.g., "claude-sonnet-4-5", "claude-opus-4-1" */
+  model: string;
+  /** Backup models to try if primary fails (default: []) */
+  backupModels?: string[];
+  /** Default parameters - uses MessageCreateParamsNonStreaming from @anthropic-ai/sdk */
+  config?: Partial<Omit<MessageCreateParamsNonStreaming, "model" | "messages">>;
+  /** Retry configuration */
+  retryConfig?: {
+    timeout?: number;
+    retries?: number;
+  };
+}
+
+/**
+ * Type guard for errors with status/code properties
+ */
+interface ErrorWithStatus {
+  status?: number;
+  code?: string;
+  message?: string;
+  type?: string;
+}
+
+/**
+ * Type guard to check if error is ErrorWithStatus
+ */
+function isErrorWithStatus(error: unknown): error is ErrorWithStatus {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    ("status" in error || "code" in error || "message" in error)
+  );
+}
+
+/**
+ * Safely extract error message
+ */
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (isErrorWithStatus(error) && error.message) {
+    return error.message;
+  }
+  return String(error);
+}
+
+/**
+ * Determines if an error should trigger backup model usage
+ */
+const shouldUseBackupModel = (error: unknown): boolean => {
+  if (!isErrorWithStatus(error)) {
+    return false;
+  }
+
+  // Server errors
+  if (error.status === 500 || error.status === 503 || error.status === 529) {
+    return true;
+  }
+
+  // Rate limiting
+  if (error.status === 429) {
+    return true;
+  }
+
+  // Model overloaded or unavailable
+  if (
+    error.type === "overloaded_error" ||
+    error.type === "api_error" ||
+    error.code === "overloaded"
+  ) {
+    return true;
+  }
+
+  const message = getErrorMessage(error);
+  if (
+    message.includes("overloaded") ||
+    message.includes("unavailable") ||
+    message.includes("internal error") ||
+    message.includes("Internal error")
+  ) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Anthropic provider implementation with backup models and retry logic
+ */
+export class AnthropicProvider implements AiProvider {
+  public readonly name = "anthropic";
+  private client: Anthropic;
+  private primaryModel: string;
+  private backupModels: string[];
+  private config?: Partial<
+    Omit<MessageCreateParamsNonStreaming, "model" | "messages">
+  >;
+  private retryConfig: { timeout: number; retries: number };
+
+  constructor(options: AnthropicProviderOptions) {
+    const { apiKey, model, backupModels = [], config, retryConfig } = options;
+
+    if (!apiKey) {
+      throw new Error("Anthropic API key is required");
+    }
+
+    if (!model) {
+      throw new Error("Model is required. Example: 'claude-sonnet-4-5'");
+    }
+
+    this.client = new Anthropic({
+      apiKey,
+    });
+    this.primaryModel = model;
+    this.backupModels = backupModels;
+    this.config = config;
+    this.retryConfig = {
+      timeout: retryConfig?.timeout || DEFAULT_RETRY_CONFIG.timeout,
+      retries: retryConfig?.retries || DEFAULT_RETRY_CONFIG.retries,
+    };
+  }
+
+  async generateMessage<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): Promise<GenerateMessageOutput> {
+    return this.generateWithBackup(input);
+  }
+
+  async *generateMessageStream<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk> {
+    yield* this.generateStreamWithBackup(input);
+  }
+
+  private async generateWithBackup<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): Promise<GenerateMessageOutput> {
+    // Try primary model first
+    try {
+      return await this.generateWithModel(this.primaryModel, input);
+    } catch (primaryError: unknown) {
+      const primaryErrMsg = getErrorMessage(primaryError);
+      console.warn(
+        `[ANTHROPIC] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
+      );
+
+      if (!shouldUseBackupModel(primaryError)) {
+        throw primaryError;
+      }
+
+      console.log(`[ANTHROPIC] Trying backup models`);
+
+      let lastBackupError: unknown = primaryError;
+
+      for (let i = 0; i < this.backupModels.length; i++) {
+        const backupModel = this.backupModels[i];
+        console.log(
+          `[ANTHROPIC] Trying backup model ${i + 1}/${
+            this.backupModels.length
+          }: ${backupModel}`
+        );
+
+        try {
+          const result = await this.generateWithModel(backupModel, input);
+          console.log(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
+          return result;
+        } catch (backupError: unknown) {
+          const backupErrMsg = getErrorMessage(backupError);
+          console.warn(
+            `[ANTHROPIC] Backup model ${backupModel} failed: ${backupErrMsg}`
+          );
+          lastBackupError = backupError;
+
+          if (
+            !shouldUseBackupModel(backupError) &&
+            i < this.backupModels.length - 1
+          ) {
+            console.log(
+              `[ANTHROPIC] Backup model error doesn't qualify for further attempts`
+            );
+            break;
+          }
+        }
+      }
+
+      const lastBackupErrMsg = getErrorMessage(lastBackupError);
+      console.error(
+        `[ANTHROPIC] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
+      );
+      throw lastBackupError;
+    }
+  }
+
+  private async generateWithModel<TContext = unknown>(
+    model: string,
+    input: GenerateMessageInput<TContext>
+  ): Promise<GenerateMessageOutput> {
+    const operation = async (): Promise<GenerateMessageOutput> => {
+      // Anthropic requires max_tokens to be specified
+      const maxTokens = input.parameters?.maxOutputTokens || 4096;
+
+      const params: MessageCreateParamsNonStreaming = {
+        model,
+        max_tokens: maxTokens,
+        messages: [
+          {
+            role: "user",
+            content: input.prompt,
+          },
+        ],
+        ...this.config,
+      };
+
+      // Handle JSON mode if requested
+      // Note: Anthropic doesn't have a native JSON mode like OpenAI,
+      // but we can add it to the system prompt
+      if (input.parameters?.jsonMode) {
+        // Add system message requesting JSON output
+        const systemPrompt =
+          "You must respond with valid JSON only. Do not include any text outside the JSON structure.";
+
+        // Merge with existing system if present
+        if (typeof this.config?.system === "string") {
+          params.system = `${this.config.system}\n\n${systemPrompt}`;
+        } else if (Array.isArray(this.config?.system)) {
+          params.system = [
+            ...this.config.system,
+            {
+              type: "text" as const,
+              text: systemPrompt,
+            },
+          ];
+        } else {
+          params.system = systemPrompt;
+        }
+      }
+
+      const response = await this.client.messages.create(params);
+
+      // Extract text from response
+      const textContent = response.content.find(
+        (block) => block.type === "text"
+      );
+      const message = textContent?.type === "text" ? textContent.text : "";
+
+      if (!message) {
+        throw new Error("No response from Anthropic");
+      }
+
+      // Parse JSON response if JSON mode was enabled
+      let structured: AgentStructuredResponse | undefined;
+      if (input.parameters?.jsonMode) {
+        try {
+          structured = JSON.parse(message) as AgentStructuredResponse;
+        } catch (error) {
+          console.warn("[ANTHROPIC] Failed to parse JSON response:", error);
+          // Fall back to treating the message as plain text
+        }
+      }
+
+      return {
+        message,
+        metadata: {
+          model: response.model,
+          stopReason: response.stop_reason,
+          tokensUsed:
+            response.usage.input_tokens + response.usage.output_tokens,
+          promptTokens: response.usage.input_tokens,
+          completionTokens: response.usage.output_tokens,
+        },
+        structured,
+      };
+    };
+
+    return withTimeoutAndRetry(
+      operation,
+      this.retryConfig.timeout,
+      this.retryConfig.retries,
+      `Anthropic ${model}`
+    );
+  }
+
+  private async *generateStreamWithBackup<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk> {
+    // Try primary model first
+    try {
+      yield* this.generateStreamWithModel(this.primaryModel, input);
+    } catch (primaryError: unknown) {
+      const primaryErrMsg = getErrorMessage(primaryError);
+      console.warn(
+        `[ANTHROPIC] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
+      );
+
+      if (!shouldUseBackupModel(primaryError)) {
+        throw primaryError;
+      }
+
+      console.log(`[ANTHROPIC] Trying backup models for streaming`);
+
+      let lastBackupError: unknown = primaryError;
+
+      for (let i = 0; i < this.backupModels.length; i++) {
+        const backupModel = this.backupModels[i];
+        console.log(
+          `[ANTHROPIC] Trying backup model ${i + 1}/${
+            this.backupModels.length
+          }: ${backupModel}`
+        );
+
+        try {
+          yield* this.generateStreamWithModel(backupModel, input);
+          console.log(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
+          return;
+        } catch (backupError: unknown) {
+          const backupErrMsg = getErrorMessage(backupError);
+          console.warn(
+            `[ANTHROPIC] Backup model ${backupModel} failed: ${backupErrMsg}`
+          );
+          lastBackupError = backupError;
+
+          if (
+            !shouldUseBackupModel(backupError) &&
+            i < this.backupModels.length - 1
+          ) {
+            console.log(
+              `[ANTHROPIC] Backup model error doesn't qualify for further attempts`
+            );
+            break;
+          }
+        }
+      }
+
+      const lastBackupErrMsg = getErrorMessage(lastBackupError);
+      console.error(
+        `[ANTHROPIC] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
+      );
+      throw lastBackupError;
+    }
+  }
+
+  private async *generateStreamWithModel<TContext = unknown>(
+    model: string,
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk> {
+    // Anthropic requires max_tokens to be specified
+    const maxTokens = input.parameters?.maxOutputTokens || 4096;
+
+    const params = {
+      model,
+      max_tokens: maxTokens,
+      messages: [
+        {
+          role: "user" as const,
+          content: input.prompt,
+        },
+      ],
+      stream: true,
+      ...this.config,
+    };
+
+    // Handle JSON mode if requested
+    if (input.parameters?.jsonMode) {
+      const systemPrompt =
+        "You must respond with valid JSON only. Do not include any text outside the JSON structure.";
+
+      if (typeof this.config?.system === "string") {
+        params.system = `${this.config.system}\n\n${systemPrompt}`;
+      } else if (Array.isArray(this.config?.system)) {
+        params.system = [
+          ...this.config.system,
+          {
+            type: "text" as const,
+            text: systemPrompt,
+          },
+        ];
+      } else {
+        params.system = systemPrompt;
+      }
+    }
+
+    const stream = this.client.messages.stream(params);
+
+    let accumulated = "";
+    let currentModel = model;
+    let stopReason: string | undefined;
+    let inputTokens = 0;
+    let outputTokens = 0;
+
+    for await (const chunk of stream) {
+      if (chunk.type === "message_start") {
+        currentModel = chunk.message.model;
+        inputTokens = chunk.message.usage.input_tokens;
+      } else if (chunk.type === "content_block_delta") {
+        if (chunk.delta.type === "text_delta") {
+          const delta = chunk.delta.text;
+          accumulated += delta;
+          yield {
+            delta,
+            accumulated,
+            done: false,
+          };
+        }
+      } else if (chunk.type === "message_delta") {
+        stopReason = chunk.delta.stop_reason || undefined;
+        outputTokens = chunk.usage.output_tokens;
+      }
+    }
+
+    // Parse JSON response if JSON mode was enabled
+    let structured: AgentStructuredResponse | undefined;
+    if (input.parameters?.jsonMode && accumulated) {
+      try {
+        structured = JSON.parse(accumulated) as AgentStructuredResponse;
+      } catch (error) {
+        console.warn(
+          "[ANTHROPIC] Failed to parse JSON response in stream:",
+          error
+        );
+      }
+    }
+
+    // Yield final chunk
+    yield {
+      delta: "",
+      accumulated,
+      done: true,
+      metadata: {
+        model: currentModel,
+        stopReason,
+        tokensUsed: inputTokens + outputTokens,
+        promptTokens: inputTokens,
+        completionTokens: outputTokens,
+      },
+      structured,
+    };
+  }
+}