@falai/agent 0.1.2 → 0.1.4

package/dist/cjs/core/Route.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Route (Journey) DSL implementation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = void 0;
+const State_1 = require("./State");
+let routeIdCounter = 0;
+/**
+ * Represents a conversational route/journey
+ */
+class Route {
+    constructor(options) {
+        this.guidelines = [];
+        this.id = `route_${++routeIdCounter}_${options.title
+            .toLowerCase()
+            .replace(/\s+/g, "_")}`;
+        this.title = options.title;
+        this.description = options.description;
+        this.conditions = options.conditions || [];
+        this.initialState = new State_1.State(this.id, "Initial state");
+        // Initialize guidelines from options
+        if (options.guidelines) {
+            options.guidelines.forEach((guideline) => {
+                this.createGuideline(guideline);
+            });
+        }
+    }
+    /**
+     * Create a guideline specific to this route
+     */
+    createGuideline(guideline) {
+        this.guidelines.push({
+            ...guideline,
+            id: guideline.id || `guideline_${this.id}_${this.guidelines.length}`,
+            enabled: guideline.enabled !== false, // Default to true
+        });
+        return this;
+    }
+    /**
+     * Get all guidelines for this route
+     */
+    getGuidelines() {
+        return [...this.guidelines];
+    }
+    /**
+     * Get route reference
+     */
+    getRef() {
+        return {
+            id: this.id,
+        };
+    }
+    /**
+     * Create a route reference that includes this route instance
+     * Useful for disambiguation
+     */
+    toRef() {
+        return {
+            id: this.id,
+            route: this,
+        };
+    }
+    /**
+     * Get all states in this route (via traversal from initial state)
+     */
+    getAllStates() {
+        const visited = new Set();
+        const states = [];
+        const queue = [this.initialState];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (visited.has(current.id)) {
+                continue;
+            }
+            visited.add(current.id);
+            states.push(current);
+            // Add target states from transitions
+            for (const transition of current.getTransitions()) {
+                const target = transition.getTarget();
+                if (target && !visited.has(target.id)) {
+                    queue.push(target);
+                }
+            }
+        }
+        return states;
+    }
+    /**
+     * Get a description of the route structure for debugging
+     */
+    describe() {
+        const lines = [
+            `Route: ${this.title}`,
+            `ID: ${this.id}`,
+            `Description: ${this.description || "N/A"}`,
+            `Conditions: ${this.conditions.join(", ") || "None"}`,
+            "",
+            "States:",
+        ];
+        const states = this.getAllStates();
+        for (const state of states) {
+            lines.push(`  - ${state.id}${state.description ? `: ${state.description}` : ""}`);
+            const transitions = state.getTransitions();
+            for (const transition of transitions) {
+                lines.push(`    -> ${transition.describe()}`);
+            }
+        }
+        return lines.join("\n");
+    }
+}
+exports.Route = Route;
+//# sourceMappingURL=Route.js.map

package/dist/cjs/core/Route.js.map

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

package/dist/cjs/core/State.d.ts

@@ -0,0 +1,50 @@
+/**
+ * State in the route DSL
+ */
+import type { StateRef, TransitionSpec, TransitionResult } from "../types/route";
+import type { Guideline } from "../types/agent";
+import { Transition } from "./Transition";
+/**
+ * Represents a state within a route
+ */
+export declare class State<TContext = unknown> {
+    readonly routeId: string;
+    readonly description?: string | undefined;
+    readonly id: string;
+    private transitions;
+    private guidelines;
+    constructor(routeId: string, description?: string | undefined);
+    /**
+     * 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<TContext>, condition?: string): TransitionResult<TContext>;
+    /**
+     * Add a guideline specific to this state
+     */
+    addGuideline(guideline: Guideline): void;
+    /**
+     * Get guidelines for this state
+     */
+    getGuidelines(): Guideline[];
+    /**
+     * Get all transitions from this state
+     */
+    getTransitions(): Transition<TContext>[];
+    /**
+     * Get state reference
+     */
+    getRef(): StateRef;
+    /**
+     * Create a state reference with transitionTo capability for chaining
+     */
+    private createStateRefWithTransition;
+    /**
+     * Create a terminal state reference (for END_ROUTE)
+     */
+    private createTerminalRef;
+}
+//# sourceMappingURL=State.d.ts.map

package/dist/cjs/core/State.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"State.d.ts","sourceRoot":"","sources":["../../../src/core/State.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1C;;GAEG;AACH,qBAAa,KAAK,CAAC,QAAQ,GAAG,OAAO;aAMjB,OAAO,EAAE,MAAM;aACf,WAAW,CAAC,EAAE,MAAM;IANtC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,UAAU,CAAmB;gBAGnB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,YAAA;IAKtC;;;;;;OAMG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,GACjB,gBAAgB,CAAC,QAAQ,CAAC;IAiD7B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,aAAa,IAAI,SAAS,EAAE;IAI5B;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE;IAIxC;;OAEG;IACH,MAAM,IAAI,QAAQ;IAOlB;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAkBpC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAkB1B"}

package/dist/cjs/core/State.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * State in the route DSL
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.State = void 0;
+const constants_1 = require("../constants");
+const Transition_1 = require("./Transition");
+let stateIdCounter = 0;
+/**
+ * Represents a state within a route
+ */
+class State {
+    constructor(routeId, description) {
+        this.routeId = routeId;
+        this.description = description;
+        this.transitions = [];
+        this.guidelines = [];
+        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, condition) {
+        // Handle END_ROUTE
+        if (spec.state &&
+            typeof spec.state === "symbol" &&
+            spec.state === constants_1.END_ROUTE) {
+            const endTransition = new Transition_1.Transition(this.getRef(), { state: constants_1.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_1.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_1.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) {
+        this.guidelines.push(guideline);
+    }
+    /**
+     * Get guidelines for this state
+     */
+    getGuidelines() {
+        return [...this.guidelines];
+    }
+    /**
+     * Get all transitions from this state
+     */
+    getTransitions() {
+        return [...this.transitions];
+    }
+    /**
+     * Get state reference
+     */
+    getRef() {
+        return {
+            id: this.id,
+            routeId: this.routeId,
+        };
+    }
+    /**
+     * Create a state reference with transitionTo capability for chaining
+     */
+    createStateRefWithTransition(ref, state) {
+        const stateInstance = state || this;
+        return {
+            ...ref,
+            transitionTo: (spec, condition) => stateInstance.transitionTo(spec, condition),
+        };
+    }
+    /**
+     * Create a terminal state reference (for END_ROUTE)
+     */
+    createTerminalRef() {
+        const terminalRef = {
+            id: "END",
+            routeId: this.routeId,
+        };
+        return {
+            ...terminalRef,
+            transitionTo: () => {
+                throw new Error("Cannot transition from END_ROUTE state");
+            },
+        };
+    }
+}
+exports.State = State;
+//# sourceMappingURL=State.js.map

package/dist/cjs/core/State.js.map

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

package/dist/cjs/core/Tool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Tool definition and creation utilities
+ */
+import type { ToolContext, ToolHandler, ToolRef, ToolResult } from "../types/tool";
+/**
+ * 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 declare function defineTool<TContext, TArgs extends unknown[], TResult>(name: string, handler: ToolHandler<TContext, TArgs, TResult>, options?: {
+    description?: string;
+    parameters?: unknown;
+}): ToolRef<TContext, TArgs, TResult>;
+/**
+ * Re-export types for convenience
+ */
+export type { ToolContext, ToolHandler, ToolRef, ToolResult };
+//# sourceMappingURL=Tool.d.ts.map

package/dist/cjs/core/Tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../../src/core/Tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,UAAU,EACX,MAAM,eAAe,CAAC;AAIvB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EACnE,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,EAC9C,OAAO,CAAC,EAAE;IACR,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GACA,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAUnC;AAED;;GAEG;AACH,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/cjs/core/Tool.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Tool definition and creation utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTool = defineTool;
+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}` };
+ *   }
+ * );
+ * ```
+ */
+function defineTool(name, handler, options) {
+    const id = `tool_${++toolIdCounter}_${name}`;
+    return {
+        id,
+        name,
+        handler,
+        description: options?.description,
+        parameters: options?.parameters,
+    };
+}
+//# sourceMappingURL=Tool.js.map

package/dist/cjs/core/Tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tool.js","sourceRoot":"","sources":["../../../src/core/Tool.ts"],"names":[],"mappings":";AAAA;;GAEG;;AA6BH,gCAiBC;AArCD,IAAI,aAAa,GAAG,CAAC,CAAC;AAEtB;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,UAAU,CACxB,IAAY,EACZ,OAA8C,EAC9C,OAGC;IAED,MAAM,EAAE,GAAG,QAAQ,EAAE,aAAa,IAAI,IAAI,EAAE,CAAC;IAE7C,OAAO;QACL,EAAE;QACF,IAAI;QACJ,OAAO;QACP,WAAW,EAAE,OAAO,EAAE,WAAW;QACjC,UAAU,EAAE,OAAO,EAAE,UAAU;KAChC,CAAC;AACJ,CAAC"}

package/dist/cjs/core/Transition.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Transition between states in the route DSL
+ */
+import type { StateRef, TransitionSpec } from "../types/route";
+import type { State } from "./State";
+/**
+ * Represents a transition from one state to another
+ */
+export declare class Transition<TContext = unknown> {
+    readonly source: StateRef;
+    readonly spec: TransitionSpec<TContext>;
+    readonly condition?: string | undefined;
+    private target?;
+    constructor(source: StateRef, spec: TransitionSpec<TContext>, condition?: string | undefined);
+    /**
+     * Set the target state for this transition
+     */
+    setTarget(state: State<TContext>): void;
+    /**
+     * Get the target state
+     */
+    getTarget(): State<TContext> | undefined;
+    /**
+     * Check if this transition has a condition
+     */
+    hasCondition(): boolean;
+    /**
+     * Get transition description for logging/debugging
+     */
+    describe(): string;
+}
+//# sourceMappingURL=Transition.d.ts.map

package/dist/cjs/core/Transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transition.d.ts","sourceRoot":"","sources":["../../../src/core/Transition.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;GAEG;AACH,qBAAa,UAAU,CAAC,QAAQ,GAAG,OAAO;aAItB,MAAM,EAAE,QAAQ;aAChB,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC;aAC9B,SAAS,CAAC,EAAE,MAAM;IALpC,OAAO,CAAC,MAAM,CAAC,CAAkB;gBAGf,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,YAAA;IAGpC;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,IAAI;IAIvC;;OAEG;IACH,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,SAAS;IAIxC;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAsBnB"}

package/dist/cjs/core/Transition.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Transition between states in the route DSL
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transition = void 0;
+/**
+ * Represents a transition from one state to another
+ */
+class Transition {
+    constructor(source, spec, condition) {
+        this.source = source;
+        this.spec = spec;
+        this.condition = condition;
+    }
+    /**
+     * Set the target state for this transition
+     */
+    setTarget(state) {
+        this.target = state;
+    }
+    /**
+     * Get the target state
+     */
+    getTarget() {
+        return this.target;
+    }
+    /**
+     * Check if this transition has a condition
+     */
+    hasCondition() {
+        return !!this.condition;
+    }
+    /**
+     * Get transition description for logging/debugging
+     */
+    describe() {
+        const parts = [];
+        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}`;
+    }
+}
+exports.Transition = Transition;
+//# sourceMappingURL=Transition.js.map

package/dist/cjs/core/Transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transition.js","sourceRoot":"","sources":["../../../src/core/Transition.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAKH;;GAEG;AACH,MAAa,UAAU;IAGrB,YACkB,MAAgB,EAChB,IAA8B,EAC9B,SAAkB;QAFlB,WAAM,GAAN,MAAM,CAAU;QAChB,SAAI,GAAJ,IAAI,CAA0B;QAC9B,cAAS,GAAT,SAAS,CAAS;IACjC,CAAC;IAEJ;;OAEG;IACH,SAAS,CAAC,KAAsB;QAC9B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACpB,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACxC,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAEzE,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,UAAU,IAAI,aAAa,EAAE,CAAC;IAChE,CAAC;CACF;AAvDD,gCAuDC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @falai/agent - Standalone AI Agent framework
+ *
+ * A strongly-typed, modular agent framework with route DSL and AI provider strategy
+ */
+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";
+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";
+export { END_ROUTE } from "./constants";
+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, AgentStructuredResponse, 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";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,YAAY,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAGhF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,YAAY,EACV,YAAY,EACZ,IAAI,EACJ,SAAS,EACT,UAAU,EACV,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEzD,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,OAAO,GACR,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,aAAa,EACb,eAAe,EACf,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,YAAY,EACV,WAAW,IAAI,YAAY,EAC3B,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * @falai/agent - Standalone AI Agent framework
+ *
+ * A strongly-typed, modular agent framework with route DSL and AI provider strategy
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SectionStatus = exports.EventSource = exports.EventKind = exports.CompositionMode = exports.END_ROUTE = exports.OpenRouterProvider = exports.OpenAIProvider = exports.GeminiProvider = exports.BuiltInSection = exports.PromptBuilder = exports.createToolEvent = exports.createMessageEvent = exports.adaptEvent = exports.DomainRegistry = exports.defineTool = exports.Observation = exports.Transition = exports.State = exports.Route = exports.Agent = void 0;
+// Core
+var Agent_1 = require("./core/Agent");
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return Agent_1.Agent; } });
+var Route_1 = require("./core/Route");
+Object.defineProperty(exports, "Route", { enumerable: true, get: function () { return Route_1.Route; } });
+var State_1 = require("./core/State");
+Object.defineProperty(exports, "State", { enumerable: true, get: function () { return State_1.State; } });
+var Transition_1 = require("./core/Transition");
+Object.defineProperty(exports, "Transition", { enumerable: true, get: function () { return Transition_1.Transition; } });
+var Observation_1 = require("./core/Observation");
+Object.defineProperty(exports, "Observation", { enumerable: true, get: function () { return Observation_1.Observation; } });
+var Tool_1 = require("./core/Tool");
+Object.defineProperty(exports, "defineTool", { enumerable: true, get: function () { return Tool_1.defineTool; } });
+var DomainRegistry_1 = require("./core/DomainRegistry");
+Object.defineProperty(exports, "DomainRegistry", { enumerable: true, get: function () { return DomainRegistry_1.DomainRegistry; } });
+var Events_1 = require("./core/Events");
+Object.defineProperty(exports, "adaptEvent", { enumerable: true, get: function () { return Events_1.adaptEvent; } });
+Object.defineProperty(exports, "createMessageEvent", { enumerable: true, get: function () { return Events_1.createMessageEvent; } });
+Object.defineProperty(exports, "createToolEvent", { enumerable: true, get: function () { return Events_1.createToolEvent; } });
+var PromptBuilder_1 = require("./core/PromptBuilder");
+Object.defineProperty(exports, "PromptBuilder", { enumerable: true, get: function () { return PromptBuilder_1.PromptBuilder; } });
+var PromptBuilder_2 = require("./core/PromptBuilder");
+Object.defineProperty(exports, "BuiltInSection", { enumerable: true, get: function () { return PromptBuilder_2.BuiltInSection; } });
+// Providers
+var GeminiProvider_1 = require("./providers/GeminiProvider");
+Object.defineProperty(exports, "GeminiProvider", { enumerable: true, get: function () { return GeminiProvider_1.GeminiProvider; } });
+var OpenAIProvider_1 = require("./providers/OpenAIProvider");
+Object.defineProperty(exports, "OpenAIProvider", { enumerable: true, get: function () { return OpenAIProvider_1.OpenAIProvider; } });
+var OpenRouterProvider_1 = require("./providers/OpenRouterProvider");
+Object.defineProperty(exports, "OpenRouterProvider", { enumerable: true, get: function () { return OpenRouterProvider_1.OpenRouterProvider; } });
+// Constants
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "END_ROUTE", { enumerable: true, get: function () { return constants_1.END_ROUTE; } });
+var agent_1 = require("./types/agent");
+Object.defineProperty(exports, "CompositionMode", { enumerable: true, get: function () { return agent_1.CompositionMode; } });
+var history_1 = require("./types/history");
+Object.defineProperty(exports, "EventKind", { enumerable: true, get: function () { return history_1.EventKind; } });
+Object.defineProperty(exports, "EventSource", { enumerable: true, get: function () { return history_1.EventSource; } });
+var prompt_1 = require("./types/prompt");
+Object.defineProperty(exports, "SectionStatus", { enumerable: true, get: function () { return prompt_1.SectionStatus; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,OAAO;AACP,sCAAqC;AAA5B,8FAAA,KAAK,OAAA;AACd,sCAAqC;AAA5B,8FAAA,KAAK,OAAA;AACd,sCAAqC;AAA5B,8FAAA,KAAK,OAAA;AACd,gDAA+C;AAAtC,wGAAA,UAAU,OAAA;AACnB,kDAAiD;AAAxC,0GAAA,WAAW,OAAA;AACpB,oCAAyC;AAAhC,kGAAA,UAAU,OAAA;AACnB,wDAAuD;AAA9C,gHAAA,cAAc,OAAA;AACvB,wCAAgF;AAAvE,oGAAA,UAAU,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAAE,yGAAA,eAAe,OAAA;AACxD,sDAAqD;AAA5C,8GAAA,aAAa,OAAA;AAEtB,sDAAsD;AAA7C,+GAAA,cAAc,OAAA;AAEvB,YAAY;AACZ,6DAA4D;AAAnD,gHAAA,cAAc,OAAA;AAEvB,6DAA4D;AAAnD,gHAAA,cAAc,OAAA;AAEvB,qEAAoE;AAA3D,wHAAA,kBAAkB,OAAA;AAG3B,YAAY;AACZ,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAUlB,uCAAgD;AAAvC,wGAAA,eAAe,OAAA;AAUxB,2CAAyD;AAAhD,oGAAA,SAAS,OAAA;AAAE,sGAAA,WAAW,OAAA;AA8B/B,yCAA+C;AAAtC,uGAAA,aAAa,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/providers/GeminiProvider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Google Gemini AI provider implementation with retry and backup models
+ */
+import type { GenerateContentConfig } from "@google/genai";
+import type { AiProvider, GenerateMessageInput, GenerateMessageOutput } from "../types/ai";
+/**
+ * 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;
+    };
+}
+/**
+ * Gemini provider implementation with backup models and retry logic
+ */
+export declare class GeminiProvider implements AiProvider {
+    readonly name = "gemini";
+    private genAI;
+    private primaryModel;
+    private backupModels;
+    private config?;
+    private retryConfig;
+    constructor(options: GeminiProviderOptions);
+    generateMessage<TContext = unknown>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>;
+    private generateWithBackup;
+    private generateWithModel;
+}
+//# sourceMappingURL=GeminiProvider.d.ts.map

package/dist/cjs/providers/GeminiProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeminiProvider.d.ts","sourceRoot":"","sources":["../../../src/providers/GeminiProvider.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAEV,qBAAqB,EAEtB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACpB,qBAAqB,EAEtB,MAAM,aAAa,CAAC;AAQrB;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gFAAgF;IAChF,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACxC,0BAA0B;IAC1B,WAAW,CAAC,EAAE;QACZ,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AA8CD;;GAEG;AACH,qBAAa,cAAe,YAAW,UAAU;IAC/C,SAAgB,IAAI,YAAY;IAChC,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAW;IAC/B,OAAO,CAAC,MAAM,CAAC,CAAiC;IAChD,OAAO,CAAC,WAAW,CAAuC;gBAE9C,OAAO,EAAE,qBAAqB;IAqBpC,eAAe,CAAC,QAAQ,GAAG,OAAO,EACtC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACpC,OAAO,CAAC,qBAAqB,CAAC;YAInB,kBAAkB;YA2DlB,iBAAiB;CAqDhC"}