@falai/agent 0.1.0-alpha2

package/dist/src/core/Route.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Route (Journey) DSL implementation
+ */
+import type { RouteOptions, RouteRef, StepOptions, RouteTransitionConfig, RouteCompletionHandler, RouteLifecycleHooks, StructuredSchema, Guideline, GuidelineMatch, Term, Tool, Template, ConditionTemplate, TemplateContext, ConditionEvaluationResult, SessionState, Event } from "../types";
+import { Step } from "./Step";
+import { Agent } from './Agent';
+/**
+ * Represents a conversational route/journey
+ */
+export declare class Route<TContext = unknown, TData = unknown> {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly identity?: Template<TContext, TData>;
+    readonly personality?: Template<TContext, TData>;
+    readonly when?: ConditionTemplate<TContext, TData>;
+    readonly skipIf?: ConditionTemplate<TContext, TData>;
+    readonly rules: Template<TContext, TData>[];
+    readonly prohibitions: Template<TContext, TData>[];
+    readonly initialStep: Step<TContext, TData>;
+    readonly endStepSpec: Omit<StepOptions<TContext, TData>, "step" | "condition" | "skipIf">;
+    readonly responseOutputSchema?: StructuredSchema;
+    readonly initialData?: Partial<TData>;
+    readonly requiredFields?: (keyof TData)[];
+    readonly optionalFields?: (keyof TData)[];
+    readonly onComplete?: string | RouteTransitionConfig<TContext, TData> | RouteCompletionHandler<TContext, TData>;
+    readonly hooks?: RouteLifecycleHooks<TContext, TData>;
+    routingExtrasSchema?: StructuredSchema;
+    guidelines: Guideline<TContext, TData>[];
+    terms: Term<TContext>[];
+    tools: Tool<TContext, TData>[];
+    knowledgeBase: Record<string, unknown>;
+    private parentAgent?;
+    constructor(options: RouteOptions<TContext, TData>, parentAgent?: Agent<TContext, TData>);
+    /**
+     * Build a sequential step machine from an array of steps
+     * @private
+     */
+    private buildSequentialSteps;
+    /**
+     * Evaluate the when condition for this route
+     * @param templateContext - Context for condition evaluation
+     * @returns Evaluation result with programmatic result and AI context strings
+     */
+    evaluateWhen(templateContext: TemplateContext<TContext, TData>): Promise<ConditionEvaluationResult>;
+    /**
+     * Evaluate the skipIf condition for this route
+     * @param templateContext - Context for condition evaluation
+     * @returns Evaluation result with programmatic result and AI context strings
+     */
+    evaluateSkipIf(templateContext: TemplateContext<TContext, TData>): Promise<ConditionEvaluationResult>;
+    /**
+     * Create a guideline specific to this route
+     */
+    createGuideline(guideline: Guideline<TContext, TData>): this;
+    /**
+     * Create a term for the route's domain glossary
+     */
+    createTerm(term: Term<TContext>): this;
+    /**
+     * Register a tool for this route
+     */
+    createTool(tool: Tool<TContext, TData>): this;
+    /**
+     * Register multiple tools for this route
+     */
+    registerTools(tools: Tool<TContext, TData>[]): this;
+    /**
+     * Add a tool to this route using the ToolManager API
+     * Creates and adds the tool to route scope in one operation
+     */
+    addTool(tool: Tool<TContext, TData>): this;
+    /**
+     * Get all guidelines for this route
+     */
+    getGuidelines(): Guideline<TContext, TData>[];
+    /**
+     * Evaluate and match active guidelines based on their conditions
+     * Returns guidelines that should be active given the current context
+     */
+    evaluateGuidelines(context?: TContext, session?: SessionState<TData>, history?: Event[]): Promise<GuidelineMatch<TContext, TData>[]>;
+    /**
+     * Get all terms for this route
+     */
+    getTerms(): Term<TContext>[];
+    /**
+     * Get all tools for this route
+     */
+    getTools(): Tool<TContext, TData>[];
+    /**
+     * Get the route's knowledge base
+     */
+    getKnowledgeBase(): Record<string, unknown>;
+    /**
+     * Get rules for this route
+     */
+    getRules(): Template<TContext, TData>[];
+    /**
+     * Get prohibitions for this route
+     */
+    getProhibitions(): Template<TContext, TData>[];
+    /**
+     * Get optional extras schema requested during routing
+     */
+    getRoutingExtrasSchema(): StructuredSchema | undefined;
+    /**
+     * Get optional structured response schema for this route's message
+     */
+    getResponseOutputSchema(): StructuredSchema | undefined;
+    getSteps(): Step<TContext, TData>[];
+    /**
+     * Get route reference
+     */
+    getRef(): RouteRef;
+    /**
+     * Get all steps in this route (via traversal from initial step)
+     */
+    getAllSteps(): Step<TContext, TData>[];
+    /**
+     * Get a specific step by ID
+     * @param stepId - The step ID to find
+     * @returns The step if found, undefined otherwise
+     */
+    getStep(stepId: string): Step<TContext, TData> | undefined;
+    /**
+     * Get a description of the route structure for debugging
+     */
+    describe(): string;
+    /**
+     * Handle data updates for this route, calling the onDataUpdate hook if configured
+     * @param data - New collected data
+     * @param previousCollected - Previously collected data
+     * @returns Modified data after hook processing, or original data if no hook
+     */
+    handleDataUpdate(data: Partial<TData>, previousCollected: Partial<TData>): Promise<Partial<TData>>;
+    /**
+     * Handle context updates for this route, calling the onContextUpdate hook if configured
+     * @param newContext - New context
+     * @param previousContext - Previous context
+     */
+    handleContextUpdate(newContext: TContext, previousContext: TContext): Promise<void>;
+    /**
+     * Export route configuration as RouteOptions for copying/cloning
+     * @returns RouteOptions that can be used to create a new route with identical configuration
+     */
+    toOptions(): RouteOptions<TContext, TData>;
+    /**
+     * Check if this route is complete based on the provided data
+     * @param data - Currently collected agent-level data
+     * @returns true if all required fields are present, false otherwise
+     *
+     * Note: Routes with no requiredFields AND no optionalFields are never complete
+     * based on data (they complete via END_ROUTE). Routes with only optionalFields
+     * are always complete (optional data doesn't block completion).
+     */
+    isComplete(data: Partial<TData>): boolean;
+    /**
+     * Get the list of missing required fields for this route
+     * @param data - Currently collected agent-level data
+     * @returns Array of missing required field keys
+     */
+    getMissingRequiredFields(data: Partial<TData>): (keyof TData)[];
+    /**
+     * Get the completion progress for this route as a percentage
+     * @param data - Currently collected agent-level data
+     * @returns Completion progress as a number between 0 and 1
+     *
+     * Note: Must be consistent with isComplete() logic
+     */
+    getCompletionProgress(data: Partial<TData>): number;
+    /**
+     * Evaluate the onComplete handler and return transition config
+     * @param session - Current session step
+     * @param context - Agent context
+     * @returns Transition config or undefined if no transition
+     */
+    evaluateOnComplete(session: {
+        data?: Partial<TData>;
+    }, context?: TContext): Promise<RouteTransitionConfig<TContext, TData> | undefined>;
+}
+//# sourceMappingURL=Route.d.ts.map

package/dist/src/core/Route.d.ts.map

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