@falai/agent 0.1.0-alpha2

package/dist/src/providers/OpenRouterProvider.js

@@ -0,0 +1,402 @@
+/**
+ * OpenRouter provider implementation
+ * OpenRouter provides access to multiple AI models through a unified OpenAI-compatible API
+ */
+import OpenAI from "openai";
+import { withTimeoutAndRetry, logger } from "../utils";
+const DEFAULT_RETRY_CONFIG = {
+    timeout: 60000,
+    retries: 3,
+};
+/**
+ * Type guard to check if error is ErrorWithStatus
+ */
+function isErrorWithStatus(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        ("status" in error || "code" in error || "message" in error));
+}
+/**
+ * Safely extract error message
+ */
+function getErrorMessage(error) {
+    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) => {
+    if (!isErrorWithStatus(error)) {
+        return false;
+    }
+    // Server errors
+    if (error.status === 500 || error.status === 503) {
+        return true;
+    }
+    // Rate limiting
+    if (error.status === 429) {
+        return true;
+    }
+    // Model not available or overloaded
+    if (error.code === "model_not_found" || error.code === "model_overloaded") {
+        return true;
+    }
+    const message = getErrorMessage(error);
+    if (message.includes("overloaded") ||
+        message.includes("unavailable") ||
+        message.includes("internal error") ||
+        message.includes("Internal error") ||
+        message.includes("capacity")) {
+        return true;
+    }
+    return false;
+};
+/**
+ * OpenRouter provider implementation
+ * Provides access to multiple AI models through OpenRouter's unified API
+ */
+export class OpenRouterProvider {
+    constructor(options) {
+        this.name = "openrouter";
+        const { apiKey, model, backupModels = [], siteUrl, siteName, config, retryConfig, } = options;
+        if (!apiKey) {
+            throw new Error("OpenRouter API key is required");
+        }
+        if (!model) {
+            throw new Error("Model is required. See https://openrouter.ai/models");
+        }
+        // Initialize OpenAI client with OpenRouter base URL
+        this.client = new OpenAI({
+            apiKey,
+            baseURL: "https://openrouter.ai/api/v1",
+            defaultHeaders: {
+                "HTTP-Referer": siteUrl || "",
+                "X-Title": siteName || "",
+            },
+        });
+        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,
+        };
+    }
+    /**
+     * Adapt common schema format to OpenRouter's format.
+     * OpenRouter is OpenAI-compatible and uses standard JSON Schema.
+     *
+     * @private
+     */
+    adaptSchemaForOpenRouter(schema) {
+        // OpenRouter is OpenAI-compatible and uses standard JSON Schema
+        // Our StructuredSchema is already JSON Schema compatible
+        return schema;
+    }
+    async generateMessage(input) {
+        return this.generateWithBackup(input);
+    }
+    async *generateMessageStream(input) {
+        yield* this.generateStreamWithBackup(input);
+    }
+    async generateWithBackup(input) {
+        // Try primary model first
+        try {
+            return await this.generateWithModel(this.primaryModel, input);
+        }
+        catch (primaryError) {
+            const primaryErrMsg = getErrorMessage(primaryError);
+            logger.warn(`[OPENROUTER] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`);
+            if (!shouldUseBackupModel(primaryError)) {
+                throw primaryError;
+            }
+            logger.debug(`[OPENROUTER] Trying backup models`);
+            let lastBackupError = primaryError;
+            for (let i = 0; i < this.backupModels.length; i++) {
+                const backupModel = this.backupModels[i];
+                logger.debug(`[OPENROUTER] Trying backup model ${i + 1}/${this.backupModels.length}: ${backupModel}`);
+                try {
+                    const result = await this.generateWithModel(backupModel, input);
+                    logger.debug(`[OPENROUTER] Backup model ${backupModel} succeeded`);
+                    return result;
+                }
+                catch (backupError) {
+                    const backupErrMsg = getErrorMessage(backupError);
+                    logger.warn(`[OPENROUTER] Backup model ${backupModel} failed: ${backupErrMsg}`);
+                    lastBackupError = backupError;
+                    if (!shouldUseBackupModel(backupError) &&
+                        i < this.backupModels.length - 1) {
+                        logger.debug(`[OPENROUTER] Backup model error doesn't qualify for further attempts`);
+                        break;
+                    }
+                }
+            }
+            const lastBackupErrMsg = getErrorMessage(lastBackupError);
+            logger.error(`[OPENROUTER] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`);
+            throw lastBackupError;
+        }
+    }
+    async generateWithModel(model, input) {
+        const operation = async () => {
+            const params = {
+                model,
+                messages: [
+                    {
+                        role: "user",
+                        content: input.prompt,
+                    },
+                ],
+                ...this.config,
+            };
+            // Override with input parameters if provided
+            if (input.parameters?.maxOutputTokens !== undefined) {
+                params.max_tokens = input.parameters.maxOutputTokens;
+            }
+            // Add tools if provided
+            if (input.tools && input.tools.length > 0) {
+                params.tools = input.tools.map((tool) => ({
+                    type: "function",
+                    function: {
+                        name: tool.name || tool.id,
+                        description: tool.description,
+                        parameters: tool.parameters, // JSON schema
+                    },
+                }));
+                params.tool_choice = "auto";
+            }
+            // Use structured output API if JSON schema is provided
+            if (input.parameters?.jsonSchema) {
+                const response = await this.client.responses.parse({
+                    model,
+                    instructions: input.prompt,
+                    input: "",
+                    reasoning: {
+                        effort: input.parameters?.reasoning?.effort || "low",
+                    },
+                    text: {
+                        format: {
+                            type: "json_schema",
+                            name: input.parameters?.schemaName || "structured_output",
+                            // Adapt common schema format to OpenRouter's format
+                            schema: this.adaptSchemaForOpenRouter(input.parameters.jsonSchema),
+                        },
+                    },
+                });
+                if (!response.output_parsed) {
+                    throw new Error("No parsed output returned from OpenRouter");
+                }
+                const structured = response.output_parsed;
+                const message = structured.message;
+                return {
+                    message,
+                    metadata: {
+                        model: response.model,
+                        tokensUsed: response.usage?.total_tokens,
+                        promptTokens: response.usage?.input_tokens,
+                        completionTokens: response.usage?.output_tokens,
+                    },
+                    structured,
+                };
+            }
+            // Fall back to regular chat completions API if no schema provided
+            const response = await this.client.chat.completions.create(params);
+            const message = response.choices[0]?.message?.content;
+            if (!message) {
+                throw new Error("No response from OpenRouter");
+            }
+            let toolCalls = [];
+            if (response.choices?.[0]?.message?.tool_calls) {
+                toolCalls = response.choices[0].message.tool_calls
+                    .filter((toolCall) => toolCall.type === "function")
+                    .map((toolCall) => {
+                    let toolCallArguments = {};
+                    try {
+                        toolCallArguments = JSON.parse(toolCall.function.arguments);
+                    }
+                    catch (error) {
+                        logger.warn(`[OPENROUTER] Failed to parse tool call arguments: ${getErrorMessage(error)}`);
+                        toolCallArguments = {};
+                    }
+                    return {
+                        toolName: toolCall.function.name,
+                        arguments: toolCallArguments,
+                    };
+                });
+            }
+            return {
+                message,
+                metadata: {
+                    model: response.model,
+                    finishReason: response.choices[0]?.finish_reason,
+                    tokensUsed: response.usage?.total_tokens,
+                    promptTokens: response.usage?.prompt_tokens,
+                    completionTokens: response.usage?.completion_tokens,
+                },
+                structured: toolCalls.length > 0
+                    ? { message, toolCalls }
+                    : undefined,
+            };
+        };
+        return withTimeoutAndRetry(operation, this.retryConfig.timeout, this.retryConfig.retries, `OpenRouter ${model}`);
+    }
+    async *generateStreamWithBackup(input) {
+        // Try primary model first
+        try {
+            yield* this.generateStreamWithModel(this.primaryModel, input);
+        }
+        catch (primaryError) {
+            const primaryErrMsg = getErrorMessage(primaryError);
+            logger.warn(`[OPENROUTER] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`);
+            if (!shouldUseBackupModel(primaryError)) {
+                throw primaryError;
+            }
+            logger.debug(`[OPENROUTER] Trying backup models for streaming`);
+            let lastBackupError = primaryError;
+            for (let i = 0; i < this.backupModels.length; i++) {
+                const backupModel = this.backupModels[i];
+                logger.debug(`[OPENROUTER] Trying backup model ${i + 1}/${this.backupModels.length}: ${backupModel}`);
+                try {
+                    yield* this.generateStreamWithModel(backupModel, input);
+                    logger.debug(`[OPENROUTER] Backup model ${backupModel} succeeded`);
+                    return;
+                }
+                catch (backupError) {
+                    const backupErrMsg = getErrorMessage(backupError);
+                    logger.warn(`[OPENROUTER] Backup model ${backupModel} failed: ${backupErrMsg}`);
+                    lastBackupError = backupError;
+                    if (!shouldUseBackupModel(backupError) &&
+                        i < this.backupModels.length - 1) {
+                        logger.debug(`[OPENROUTER] Backup model error doesn't qualify for further attempts`);
+                        break;
+                    }
+                }
+            }
+            const lastBackupErrMsg = getErrorMessage(lastBackupError);
+            logger.error(`[OPENROUTER] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`);
+            throw lastBackupError;
+        }
+    }
+    async *generateStreamWithModel(model, input) {
+        const params = {
+            ...this.config,
+            model,
+            messages: [
+                {
+                    role: "user",
+                    content: input.prompt,
+                },
+            ],
+            stream: true,
+        };
+        // Override with input parameters if provided
+        if (input.parameters?.maxOutputTokens !== undefined) {
+            params.max_tokens = input.parameters.maxOutputTokens;
+        }
+        // Add tools if provided
+        if (input.tools && input.tools.length > 0) {
+            params.tools = input.tools.map((tool) => ({
+                type: "function",
+                function: {
+                    name: tool.name || tool.id,
+                    description: tool.description,
+                    parameters: tool.parameters, // JSON schema
+                },
+            }));
+            params.tool_choice = "auto";
+        }
+        // Streaming path does not support responses.parse; if schema present,
+        // request JSON object and parse at the end.
+        if (input.parameters?.jsonSchema) {
+            params.response_format = { type: "json_object" };
+        }
+        const stream = await this.client.chat.completions.create(params);
+        let accumulated = "";
+        let currentModel = model;
+        let finishReason;
+        let promptTokens;
+        let completionTokens;
+        let totalTokens;
+        const toolCalls = [];
+        for await (const chunk of stream) {
+            currentModel = chunk.model;
+            const delta = chunk.choices[0]?.delta?.content || "";
+            // Extract tool calls from delta
+            if (chunk.choices[0]?.delta?.tool_calls) {
+                for (const toolCall of chunk.choices[0].delta.tool_calls) {
+                    if (toolCall.function) {
+                        let toolCallArguments = {};
+                        try {
+                            toolCallArguments = toolCall.function.arguments
+                                ? JSON.parse(toolCall.function.arguments)
+                                : {};
+                        }
+                        catch (error) {
+                            logger.warn(`[OPENROUTER] Failed to parse tool call arguments in stream: ${getErrorMessage(error)}`);
+                            toolCallArguments = {};
+                        }
+                        toolCalls.push({
+                            toolName: toolCall.function.name || "",
+                            arguments: toolCallArguments,
+                        });
+                    }
+                }
+            }
+            if (delta) {
+                accumulated += delta;
+                yield {
+                    delta,
+                    accumulated,
+                    done: false,
+                };
+            }
+            if (chunk.choices[0]?.finish_reason) {
+                finishReason = chunk.choices[0].finish_reason;
+            }
+            // OpenRouter may include usage in the final chunk
+            if (chunk.usage) {
+                promptTokens = chunk.usage.prompt_tokens;
+                completionTokens = chunk.usage.completion_tokens;
+                totalTokens = chunk.usage.total_tokens;
+            }
+        }
+        // Parse JSON response if schema was provided
+        let structured;
+        if (input.parameters?.jsonSchema && accumulated) {
+            try {
+                structured = JSON.parse(accumulated);
+            }
+            catch (error) {
+                logger.warn("[OPENROUTER] Failed to parse JSON response in stream:", error);
+            }
+        }
+        // If tools were used, include them in structured response
+        if (toolCalls.length > 0) {
+            structured = {
+                message: accumulated,
+                toolCalls,
+                ...structured,
+            };
+        }
+        // Yield final chunk
+        yield {
+            delta: "",
+            accumulated,
+            done: true,
+            metadata: {
+                model: currentModel,
+                finishReason,
+                tokensUsed: totalTokens,
+                promptTokens,
+                completionTokens,
+            },
+            structured,
+        };
+    }
+}
+//# sourceMappingURL=OpenRouterProvider.js.map

package/dist/src/providers/OpenRouterProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenRouterProvider.js","sourceRoot":"","sources":["../../../src/providers/OpenRouterProvider.ts"],"names":[],"mappings":"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"}

package/dist/src/providers/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AI Provider exports
+ * Centralized export point for all AI provider implementations
+ */
+export { AnthropicProvider } from "./AnthropicProvider";
+export type { AnthropicProviderOptions } from "./AnthropicProvider";
+export { GeminiProvider } from "./GeminiProvider";
+export type { GeminiProviderOptions } from "./GeminiProvider";
+export { OpenAIProvider } from "./OpenAIProvider";
+export type { OpenAIProviderOptions } from "./OpenAIProvider";
+export { OpenRouterProvider } from "./OpenRouterProvider";
+export type { OpenRouterProviderOptions } from "./OpenRouterProvider";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/src/providers/index.js

@@ -0,0 +1,9 @@
+/**
+ * AI Provider exports
+ * Centralized export point for all AI provider implementations
+ */
+export { AnthropicProvider } from "./AnthropicProvider";
+export { GeminiProvider } from "./GeminiProvider";
+export { OpenAIProvider } from "./OpenAIProvider";
+export { OpenRouterProvider } from "./OpenRouterProvider";
+//# sourceMappingURL=index.js.map

package/dist/src/providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/src/types/agent.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Agent-related type definitions
+ */
+import type { AgentStructuredResponse, AiProvider } from "./ai";
+import type { Tool } from "./tool";
+import type { RouteOptions } from "./route";
+import type { PersistenceConfig } from "./persistence";
+import type { SessionState } from "./session";
+import type { StructuredSchema } from "./schema";
+import { Template, ConditionTemplate } from "./template";
+/**
+ * Composition mode determines how the agent processes and structures responses
+ */
+export declare enum CompositionMode {
+    /** Fluid, natural conversation without strict structure */
+    FLUID = "fluid",
+    /** Canned responses with fluid fallback */
+    CANNED_FLUID = "canned_fluid",
+    /** Composited canned responses */
+    CANNED_COMPOSITED = "composited_canned",
+    /** Strict canned responses only */
+    CANNED_STRICT = "strict_canned"
+}
+/**
+ * Context lifecycle hooks for managing step persistence
+ */
+export interface ContextLifecycleHooks<TContext = unknown, TData = unknown> {
+    /**
+     * Called before respond() to get fresh context
+     * Useful for loading context from a database or cache
+     */
+    beforeRespond?: (currentContext: TContext) => Promise<TContext> | TContext;
+    /**
+     * Called after context is updated via updateContext() or tool execution
+     * Useful for persisting context to a database or cache
+     */
+    onContextUpdate?: (newContext: TContext, previousContext: TContext) => Promise<void> | void;
+    /**
+     * Called after collected data is updated (from AI response or tool execution)
+     * Useful for validation, enrichment, or persistence of collected data
+     * Return modified collected data or the same data to keep it unchanged
+     *
+     * Note: This hook now works with agent-level data collection (TData type)
+     */
+    onDataUpdate?: (data: Partial<TData>, previousCollected: Partial<TData>) => Partial<TData> | Promise<Partial<TData>>;
+}
+/**
+ * Context provider function for always-fresh context
+ * Alternative to static context, useful for loading from external sources
+ */
+export type ContextProvider<TContext = unknown> = () => Promise<TContext> | TContext;
+/**
+ * Options for creating an Agent
+ */
+export interface AgentOptions<TContext = unknown, TData = unknown> {
+    /** Display name of the agent */
+    name: string;
+    /** Detailed description of the agent's purpose and personality */
+    description?: string;
+    /** The agent's primary goal or objective */
+    goal?: string;
+    /** Optional personality/tone prompt used in prompts */
+    personality?: Template<TContext>;
+    /** Optional identity prompt defining the agent's self-concept and role */
+    identity?: Template<TContext>;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Default context data available to the agent */
+    context?: TContext;
+    /** Optional current session for convenience methods */
+    session?: SessionState;
+    /** Optional sessionId to load or create - managed by SessionManager */
+    sessionId?: string;
+    /** Context provider function for always-fresh context (alternative to static context) */
+    contextProvider?: ContextProvider<TContext>;
+    /** Lifecycle hooks for context management */
+    hooks?: ContextLifecycleHooks<TContext, TData>;
+    /** AI provider strategy for generating responses */
+    provider: AiProvider;
+    /** Composition mode for response generation */
+    compositionMode?: CompositionMode;
+    /** Initial terms for domain glossary */
+    terms?: Term<TContext, TData>[];
+    /** Initial guidelines for agent behavior */
+    guidelines?: Guideline<TContext, TData>[];
+    /** Global tools available to all routes */
+    tools?: Tool<TContext, TData, unknown>[];
+    /** Initial routes (will be instantiated as Route objects) */
+    routes?: RouteOptions<TContext, TData>[];
+    /** Optional persistence configuration for auto-saving sessions and messages */
+    persistence?: PersistenceConfig<TData>;
+    /** Knowledge base containing any JSON structure the AI should know */
+    knowledgeBase?: Record<string, unknown>;
+    /** Agent-level data schema defining the complete data structure for collection */
+    schema?: StructuredSchema;
+    /** Initial data to pre-populate when creating the agent */
+    initialData?: Partial<TData>;
+}
+/**
+ * A term in the domain glossary
+ */
+export interface Term<TContext = unknown, TData = unknown> {
+    /** Name of the term */
+    name: Template<TContext, TData>;
+    /** Description/definition of the term */
+    description: Template<TContext, TData>;
+    /** Alternative names or synonyms */
+    synonyms?: Template<TContext, TData>[];
+}
+/**
+ * A behavioral guideline for the agent
+ */
+export interface Guideline<TContext = unknown, TData = unknown> {
+    /** Unique identifier */
+    id?: string;
+    /** Condition that triggers this guideline (optional for always-active guidelines) */
+    condition?: ConditionTemplate<TContext, TData>;
+    /** Action the agent should take when the condition is met */
+    action: Template<TContext, TData>;
+    /** Whether this guideline is currently enabled */
+    enabled?: boolean;
+    /** Tags for organizing and filtering guidelines */
+    tags?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Guideline match with rationale
+ */
+export interface GuidelineMatch<TContext = unknown, TData = unknown> {
+    /** The matched guideline */
+    guideline: Guideline<TContext, TData>;
+    /** Explanation of why this guideline was matched */
+    rationale?: string;
+}
+export interface AgentResponse<TData = Record<string, unknown>> {
+    message: string;
+    session?: SessionState<TData>;
+    toolCalls?: Array<{
+        toolName: string;
+        arguments: Record<string, unknown>;
+    }>;
+    isRouteComplete?: boolean;
+}
+export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
+    delta: string;
+    accumulated: string;
+    done: boolean;
+    session?: SessionState<TData>;
+    toolCalls?: Array<{
+        toolName: string;
+        arguments: Record<string, unknown>;
+    }>;
+    isRouteComplete?: boolean;
+    metadata?: {
+        model?: string;
+        tokensUsed?: number;
+        finishReason?: string;
+        [key: string]: unknown;
+    };
+    structured?: AgentStructuredResponse;
+    error?: Error;
+}
+/**
+ * Validation error for data validation
+ */
+export interface ValidationError {
+    field: string;
+    value: unknown;
+    message: string;
+    schemaPath: string;
+}
+/**
+ * Result of data validation
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/src/types/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/types/agent.ts"],"names":[],"mappings":"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"}

package/dist/src/types/agent.js

@@ -0,0 +1,18 @@
+/**
+ * Agent-related type definitions
+ */
+/**
+ * Composition mode determines how the agent processes and structures responses
+ */
+export var CompositionMode;
+(function (CompositionMode) {
+    /** Fluid, natural conversation without strict structure */
+    CompositionMode["FLUID"] = "fluid";
+    /** Canned responses with fluid fallback */
+    CompositionMode["CANNED_FLUID"] = "canned_fluid";
+    /** Composited canned responses */
+    CompositionMode["CANNED_COMPOSITED"] = "composited_canned";
+    /** Strict canned responses only */
+    CompositionMode["CANNED_STRICT"] = "strict_canned";
+})(CompositionMode || (CompositionMode = {}));
+//# sourceMappingURL=agent.js.map

package/dist/src/types/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH;;GAEG;AACH,MAAM,CAAN,IAAY,eASX;AATD,WAAY,eAAe;IACzB,2DAA2D;IAC3D,kCAAe,CAAA;IACf,2CAA2C;IAC3C,gDAA6B,CAAA;IAC7B,kCAAkC;IAClC,0DAAuC,CAAA;IACvC,mCAAmC;IACnC,kDAA+B,CAAA;AACjC,CAAC,EATW,eAAe,KAAf,eAAe,QAS1B"}