@falai/agent 0.1.0-alpha2

package/dist/cjs/src/core/RoutingEngine.d.ts

@@ -0,0 +1,159 @@
+import type { Event, AgentOptions, StructuredSchema, RoutingDecision, SessionState, AiProvider, TemplateContext } from "../types";
+import type { Route } from "./Route";
+import type { Step } from "./Step";
+export interface CandidateStep<TContext = unknown, TData = unknown> {
+    step: Step<TContext, TData>;
+    isRouteComplete?: boolean;
+}
+export interface RoutingDecisionOutput {
+    context: string;
+    routes: Record<string, number>;
+    selectedStepId?: string;
+    stepReasoning?: string;
+    responseDirectives?: string[];
+    extractions?: Array<{
+        name: string;
+        value: any;
+        confidence?: number;
+        source?: "message" | "history";
+    }>;
+    contextUpdate?: Record<string, unknown>;
+}
+export interface RoutingEngineOptions {
+    allowRouteSwitch?: boolean;
+    switchThreshold?: number;
+    maxCandidates?: number;
+}
+export interface BuildStepSelectionPromptParams<TContext = unknown, TData = unknown> {
+    route: Route<TContext, TData>;
+    currentStep: Step<TContext, TData> | undefined;
+    candidates: CandidateStep<TContext, TData>[];
+    data: Partial<TData>;
+    history: Event[];
+    lastMessage: string;
+    agentOptions?: AgentOptions<TContext, TData>;
+    context?: TContext;
+    session?: SessionState<TData>;
+    stepConditionContext?: string[];
+}
+export interface BuildRoutingPromptParams<TContext = unknown, TData = unknown> {
+    history: Event[];
+    routes: Route<TContext, TData>[];
+    lastMessage: string;
+    agentOptions?: AgentOptions<TContext, TData>;
+    session?: SessionState<TData>;
+    activeRouteSteps?: Step<TContext, TData>[];
+    context?: TContext;
+    routeConditionContext?: string[];
+}
+export declare class RoutingEngine<TContext = unknown, TData = unknown> {
+    private readonly options?;
+    constructor(options?: RoutingEngineOptions | undefined);
+    /**
+     * Enter a route if not already in it, merging initial data
+     * @private
+     */
+    private enterRouteIfNeeded;
+    /**
+     * Optimized decision for single-route scenarios
+     * Skips route scoring and only does step selection
+     * @private
+     */
+    private decideSingleRouteStep;
+    /**
+     * Recursively traverse step chain to find first non-skipped step or END_ROUTE using new condition evaluation
+     * @private
+     */
+    private findFirstValidStepRecursiveWithConditions;
+    /**
+     * Identify valid next candidate steps using new condition evaluation system
+     * Returns step with isRouteComplete flag if route is complete (all steps skipped + has END_ROUTE transition)
+     *
+     * NEW: Automatically completes route when all required fields are collected
+     */
+    getCandidateStepsWithConditions(route: Route<TContext, TData>, currentStep: Step<TContext, TData> | undefined, templateContext: TemplateContext<TContext, TData>): Promise<CandidateStep<TContext, TData>[]>;
+    /**
+     * Full routing orchestration: builds prompt and schema, calls AI, selects route/step,
+     * and updates the session (including initialData merge when entering a new route).
+     *
+     * OPTIMIZATION: If there's only 1 route, skips route scoring and only does step selection.
+     * CROSS-ROUTE COMPLETION: Evaluates all routes for completion based on collected data.
+     */
+    decideRouteAndStep(params: {
+        routes: Route<TContext, TData>[];
+        session: SessionState<TData>;
+        history: Event[];
+        agentOptions?: AgentOptions<TContext, TData>;
+        provider: AiProvider;
+        context: TContext;
+        signal?: AbortSignal;
+    }): Promise<{
+        selectedRoute?: Route<TContext, TData>;
+        selectedStep?: Step<TContext, TData>;
+        responseDirectives?: string[];
+        session: SessionState<TData>;
+        isRouteComplete?: boolean;
+        completedRoutes?: Route<TContext, TData>[];
+    }>;
+    /**
+     * Filter routes based on skipIf conditions
+     * @param routes - All available routes
+     * @param templateContext - Context for condition evaluation
+     * @returns Object with eligible routes and collected AI context strings
+     */
+    filterRoutesBySkipIf(routes: Route<TContext, TData>[], templateContext: TemplateContext<TContext, TData>): Promise<{
+        eligibleRoutes: Route<TContext, TData>[];
+        aiContextStrings: string[];
+    }>;
+    /**
+     * Filter routes based on when conditions
+     * @param routes - Routes that passed skipIf filtering
+     * @param templateContext - Context for condition evaluation
+     * @returns Object with eligible routes and collected AI context strings
+     */
+    filterRoutesByWhen(routes: Route<TContext, TData>[], templateContext: TemplateContext<TContext, TData>): Promise<{
+        eligibleRoutes: Route<TContext, TData>[];
+        aiContextStrings: string[];
+    }>;
+    /**
+     * Evaluate all routes for completion based on collected data
+     * @param routes - All available routes
+     * @param data - Currently collected agent-level data
+     * @returns Array of routes that are complete
+     */
+    evaluateRouteCompletions(routes: Route<TContext, TData>[], data: Partial<TData>): Route<TContext, TData>[];
+    /**
+     * Get completion status for all routes
+     * @param routes - All available routes
+     * @param data - Currently collected agent-level data
+     * @returns Map of route ID to completion progress (0-1)
+     */
+    getRouteCompletionStatus(routes: Route<TContext, TData>[], data: Partial<TData>): Map<string, number>;
+    /**
+     * Find the best route to continue based on completion status and user intent
+     * Prioritizes routes that are partially complete but not finished
+     * IMPORTANT: Completed routes are excluded to prevent re-entering finished tasks
+     * @param routes - All available routes
+     * @param data - Currently collected agent-level data
+     * @param routeScores - AI-generated route scores from routing decision
+     * @returns Route that should be prioritized for continuation
+     */
+    selectOptimalRoute(routes: Route<TContext, TData>[], data: Partial<TData>, routeScores: Record<string, number>): Route<TContext, TData> | undefined;
+    /**
+     * Build prompt for step selection within a single route
+     * @private
+     */
+    private buildStepSelectionPrompt;
+    /**
+     * Build schema for step selection
+     * @private
+     */
+    private buildStepSelectionSchema;
+    buildDynamicRoutingSchema(routes: Route<TContext, TData>[], extrasSchema?: StructuredSchema, activeRouteSteps?: Step<TContext, TData>[]): StructuredSchema;
+    buildRoutingPrompt(params: BuildRoutingPromptParams<TContext, TData>): Promise<string>;
+    decideRouteFromScores(output: RoutingDecision): {
+        routeId: string;
+        maxScore: number;
+    };
+}
+//# sourceMappingURL=RoutingEngine.d.ts.map

package/dist/cjs/src/core/RoutingEngine.d.ts.map

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