@falai/agent 0.1.0

package/src/core/State.ts

@@ -0,0 +1,153 @@
+/**
+ * State in the route DSL
+ */
+
+import type { StateRef, TransitionSpec, TransitionResult } from "@/types/route";
+import type { Guideline } from "@/types/agent";
+
+import { END_ROUTE } from "@/constants";
+import { Transition } from "@/core/Transition";
+
+let stateIdCounter = 0;
+
+/**
+ * Represents a state within a route
+ */
+export class State {
+  public readonly id: string;
+  private transitions: Transition[] = [];
+  private guidelines: Guideline[] = [];
+
+  constructor(
+    public readonly routeId: string,
+    public readonly description?: string
+  ) {
+    this.id = `state_${++stateIdCounter}`;
+  }
+
+  /**
+   * Create a transition from this state to another
+   *
+   * @param spec - Transition specification (chatState, toolState, or direct state)
+   * @param condition - Optional condition for this transition
+   * @returns Object with target state that supports chaining
+   */
+  transitionTo(spec: TransitionSpec, condition?: string): TransitionResult {
+    // Handle END_ROUTE
+    if (
+      spec.state &&
+      typeof spec.state === "symbol" &&
+      spec.state === END_ROUTE
+    ) {
+      const endTransition = new Transition(
+        this.getRef(),
+        { state: END_ROUTE },
+        condition
+      );
+      this.transitions.push(endTransition);
+
+      // Return a terminal state reference
+      return {
+        target: this.createTerminalRef(),
+      };
+    }
+
+    // Handle direct state reference
+    if (spec.state && typeof spec.state !== "symbol") {
+      const transition = new Transition(this.getRef(), spec, condition);
+      this.transitions.push(transition);
+
+      return {
+        target: this.createStateRefWithTransition(spec.state),
+      };
+    }
+
+    // Create new target state for chatState or toolState
+    const targetState = new State(this.routeId, spec.chatState);
+    const transition = new Transition(this.getRef(), spec, condition);
+    transition.setTarget(targetState);
+
+    this.transitions.push(transition);
+
+    return {
+      target: this.createStateRefWithTransition(
+        targetState.getRef(),
+        targetState
+      ),
+    };
+  }
+
+  /**
+   * Add a guideline specific to this state
+   */
+  addGuideline(guideline: Guideline): void {
+    this.guidelines.push(guideline);
+  }
+
+  /**
+   * Get guidelines for this state
+   */
+  getGuidelines(): Guideline[] {
+    return [...this.guidelines];
+  }
+
+  /**
+   * Get all transitions from this state
+   */
+  getTransitions(): Transition[] {
+    return [...this.transitions];
+  }
+
+  /**
+   * Get state reference
+   */
+  getRef(): StateRef {
+    return {
+      id: this.id,
+      routeId: this.routeId,
+    };
+  }
+
+  /**
+   * Create a state reference with transitionTo capability for chaining
+   */
+  private createStateRefWithTransition(
+    ref: StateRef,
+    state?: State
+  ): StateRef & {
+    transitionTo: (
+      spec: TransitionSpec,
+      condition?: string
+    ) => TransitionResult;
+  } {
+    const stateInstance = state || this;
+
+    return {
+      ...ref,
+      transitionTo: (spec: TransitionSpec, condition?: string) =>
+        stateInstance.transitionTo(spec, condition),
+    };
+  }
+
+  /**
+   * Create a terminal state reference (for END_ROUTE)
+   */
+  private createTerminalRef(): StateRef & {
+    transitionTo: (
+      spec: TransitionSpec,
+      condition?: string
+    ) => TransitionResult;
+  } {
+    const terminalRef: StateRef = {
+      id: "END",
+      routeId: this.routeId,
+    };
+
+    return {
+      ...terminalRef,
+      transitionTo: () => {
+        throw new Error("Cannot transition from END_ROUTE state");
+      },
+    };
+  }
+}

package/src/core/Tool.ts

@@ -0,0 +1,54 @@
+/**
+ * Tool definition and creation utilities
+ */
+
+import type {
+  ToolContext,
+  ToolHandler,
+  ToolRef,
+  ToolResult,
+} from "@/types/tool";
+
+let toolIdCounter = 0;
+
+/**
+ * Define a new tool with type-safe context and arguments
+ *
+ * @param name - Name of the tool
+ * @param handler - Handler function that executes the tool
+ * @param options - Optional configuration
+ * @returns A reference to the defined tool
+ *
+ * @example
+ * ```ts
+ * const getTool = defineTool<MyContext, [string, number], string>(
+ *   'get_data',
+ *   async ({ context }, id, count) => {
+ *     return { data: `Retrieved ${count} items for ${id}` };
+ *   }
+ * );
+ * ```
+ */
+export function defineTool<TContext, TArgs extends unknown[], TResult>(
+  name: string,
+  handler: ToolHandler<TContext, TArgs, TResult>,
+  options?: {
+    description?: string;
+    parameters?: unknown;
+  }
+): ToolRef<TContext, TArgs, TResult> {
+  const id = `tool_${++toolIdCounter}_${name}`;
+
+  return {
+    id,
+    name,
+    handler,
+    description: options?.description,
+    parameters: options?.parameters,
+  };
+}
+
+/**
+ * Re-export types for convenience
+ */
+export type { ToolContext, ToolHandler, ToolRef, ToolResult };

package/src/core/Transition.ts

@@ -0,0 +1,66 @@
+/**
+ * Transition between states in the route DSL
+ */
+
+import type { StateRef, TransitionSpec } from "@/types/route";
+import type { State } from "@/core/State";
+
+/**
+ * Represents a transition from one state to another
+ */
+export class Transition {
+  private target?: State;
+
+  constructor(
+    public readonly source: StateRef,
+    public readonly spec: TransitionSpec,
+    public readonly condition?: string
+  ) {}
+
+  /**
+   * Set the target state for this transition
+   */
+  setTarget(state: State): void {
+    this.target = state;
+  }
+
+  /**
+   * Get the target state
+   */
+  getTarget(): State | undefined {
+    return this.target;
+  }
+
+  /**
+   * Check if this transition has a condition
+   */
+  hasCondition(): boolean {
+    return !!this.condition;
+  }
+
+  /**
+   * Get transition description for logging/debugging
+   */
+  describe(): string {
+    const parts: string[] = [];
+
+    if (this.spec.chatState) {
+      parts.push(`chat: "${this.spec.chatState}"`);
+    }
+    if (this.spec.toolState) {
+      parts.push(`tool: ${this.spec.toolState.name}`);
+    }
+    if (this.spec.state) {
+      if (typeof this.spec.state === "symbol") {
+        parts.push("state: END_ROUTE");
+      } else {
+        parts.push(`state: ${this.spec.state.id}`);
+      }
+    }
+
+    const transition = parts.join(", ");
+    const conditionPart = this.condition ? ` (when: ${this.condition})` : "";
+
+    return `${this.source.id} -> [${transition}]${conditionPart}`;
+  }
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * @falai/agent - Standalone AI Agent framework
+ *
+ * A strongly-typed, modular agent framework with route DSL and AI provider strategy
+ */
+
+// Core
+export { Agent } from "./core/Agent";
+export { Route } from "./core/Route";
+export { State } from "./core/State";
+export { Transition } from "./core/Transition";
+export { Observation } from "./core/Observation";
+export { defineTool } from "./core/Tool";
+export { DomainRegistry } from "./core/DomainRegistry";
+export { adaptEvent, createMessageEvent, createToolEvent } from "./core/Events";
+export { PromptBuilder } from "./core/PromptBuilder";
+export type { Customer, AgentInfo } from "./core/PromptBuilder";
+export { BuiltInSection } from "./core/PromptBuilder";
+
+// Providers
+export { GeminiProvider } from "./providers/GeminiProvider";
+export type { GeminiProviderOptions } from "./providers/GeminiProvider";
+export { OpenAIProvider } from "./providers/OpenAIProvider";
+export type { OpenAIProviderOptions } from "./providers/OpenAIProvider";
+export { OpenRouterProvider } from "./providers/OpenRouterProvider";
+export type { OpenRouterProviderOptions } from "./providers/OpenRouterProvider";
+
+// Constants
+export { END_ROUTE } from "./constants";
+
+// Types
+export type {
+  AgentOptions,
+  Term,
+  Guideline,
+  Capability,
+  GuidelineMatch,
+} from "@/types/agent";
+export { CompositionMode } from "@/types/agent";
+
+export type {
+  Event,
+  EmittedEvent,
+  MessageEventData,
+  ToolEventData,
+  StatusEventData,
+  Participant,
+} from "@/types/history";
+export { EventKind, EventSource } from "@/types/history";
+
+export type {
+  RouteRef,
+  StateRef,
+  RouteOptions,
+  TransitionSpec,
+  TransitionResult,
+} from "@/types/route";
+
+export type {
+  ToolContext,
+  ToolResult,
+  ToolHandler,
+  ToolRef,
+} from "@/types/tool";
+
+export type {
+  AiProvider,
+  GenerateMessageInput,
+  GenerateMessageOutput,
+  ReasoningConfig,
+} from "@/types/ai";
+
+export type {
+  PromptSection,
+  ContextVariable,
+  ContextVariableValue,
+} from "@/types/prompt";
+export { SectionStatus } from "@/types/prompt";
+
+export type {
+  Observation as IObservation,
+  ObservationOptions,
+} from "@/types/observation";

package/src/providers/GeminiProvider.ts

@@ -0,0 +1,220 @@
+/**
+ * Google Gemini AI provider implementation with retry and backup models
+ */
+
+import type {
+  GoogleGenAI as GoogleGenAIType,
+  GenerateContentConfig,
+  GenerateContentResponse,
+} from "@google/genai";
+import { GoogleGenAI } from "@google/genai";
+
+import type {
+  AiProvider,
+  GenerateMessageInput,
+  GenerateMessageOutput,
+} from "@/types/ai";
+import { withTimeoutAndRetry } from "@/utils/retry";
+
+const DEFAULT_RETRY_CONFIG = {
+  timeout: 60000,
+  retries: 3,
+};
+
+/**
+ * Configuration options for Gemini provider
+ * Uses types from @google/genai package
+ */
+export interface GeminiProviderOptions {
+  /** Gemini API key */
+  apiKey: string;
+  /** Model to use (required) - e.g., "models/gemini-2.5-pro" */
+  model: string;
+  /** Backup models to try if primary fails (default: []) */
+  backupModels?: string[];
+  /** Default generation config - uses GenerateContentConfig from @google/genai */
+  config?: Partial<GenerateContentConfig>;
+  /** Retry configuration */
+  retryConfig?: {
+    timeout?: number;
+    retries?: number;
+  };
+}
+
+/**
+ * Type guard for errors with status/code properties
+ */
+interface ErrorWithStatus {
+  status?: number;
+  code?: number;
+  message?: string;
+}
+
+/**
+ * Determines if an error should trigger backup model usage
+ */
+const shouldUseBackupModel = (error: unknown): boolean => {
+  const err = error as ErrorWithStatus;
+
+  if (err?.status === 500 || err?.code === 500) {
+    return true;
+  }
+
+  const message = err?.message ?? String(error);
+  if (
+    message.includes("internal error") ||
+    message.includes("Internal error") ||
+    message.includes("INTERNAL")
+  ) {
+    return true;
+  }
+
+  if (
+    err?.status === 429 ||
+    err?.code === 429 ||
+    err?.status === 503 ||
+    err?.code === 503
+  ) {
+    return true;
+  }
+
+  if (message.includes("unavailable") || message.includes("not available")) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Gemini provider implementation with backup models and retry logic
+ */
+export class GeminiProvider implements AiProvider {
+  public readonly name = "gemini";
+  private genAI: GoogleGenAIType;
+  private primaryModel: string;
+  private backupModels: string[];
+  private config?: Partial<GenerateContentConfig>;
+  private retryConfig: { timeout: number; retries: number };
+
+  constructor(options: GeminiProviderOptions) {
+    const { apiKey, model, backupModels = [], config, retryConfig } = options;
+
+    if (!apiKey) {
+      throw new Error("Gemini API key is required");
+    }
+
+    if (!model) {
+      throw new Error("Model is required. Example: 'models/gemini-2.5-pro'");
+    }
+
+    this.genAI = new GoogleGenAI({ 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);
+  }
+
+  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 = String(primaryError);
+      console.warn(
+        `[GEMINI] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
+      );
+
+      if (!shouldUseBackupModel(primaryError)) {
+        throw primaryError;
+      }
+
+      console.log(`[GEMINI] Trying backup models`);
+
+      let lastBackupError: unknown = primaryError;
+
+      for (let i = 0; i < this.backupModels.length; i++) {
+        const backupModel = this.backupModels[i];
+        console.log(
+          `[GEMINI] Trying backup model ${i + 1}/${
+            this.backupModels.length
+          }: ${backupModel}`
+        );
+
+        try {
+          const result = await this.generateWithModel(backupModel, input);
+          console.log(`[GEMINI] Backup model ${backupModel} succeeded`);
+          return result;
+        } catch (backupError: unknown) {
+          const backupErrMsg = String(backupError);
+          console.warn(
+            `[GEMINI] Backup model ${backupModel} failed: ${backupErrMsg}`
+          );
+          lastBackupError = backupError;
+
+          if (
+            !shouldUseBackupModel(backupError) &&
+            i < this.backupModels.length - 1
+          ) {
+            console.log(
+              `[GEMINI] Backup model error doesn't qualify for further attempts`
+            );
+            break;
+          }
+        }
+      }
+
+      const lastBackupErrMsg = String(lastBackupError);
+      console.error(
+        `[GEMINI] 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> => {
+      const response: GenerateContentResponse =
+        await this.genAI.models.generateContent({
+          model,
+          contents: input.prompt,
+          config: this.config,
+        });
+
+      const message = response.text;
+      if (!message) {
+        throw new Error("No response from Gemini");
+      }
+
+      return {
+        message,
+        metadata: {
+          model,
+          tokensUsed: response.usageMetadata?.totalTokenCount,
+          promptTokens: response.usageMetadata?.promptTokenCount,
+          completionTokens: response.usageMetadata?.candidatesTokenCount,
+        },
+      };
+    };
+
+    return withTimeoutAndRetry(
+      operation,
+      this.retryConfig.timeout,
+      this.retryConfig.retries,
+      `Gemini ${model}`
+    );
+  }
+}