@falai/agent 0.1.0-alpha2

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

@@ -0,0 +1,232 @@
+/**
+ * Core Agent implementation
+ */
+import type { AgentOptions, Term, Guideline, GuidelineMatch, Tool, Event, RouteOptions, SessionState, Template, AgentResponseStreamChunk, AgentResponse, StructuredSchema, ValidationResult } from "../types";
+import type { StreamOptions, GenerateOptions, RespondParams } from "./ResponseModal";
+import { Route } from "./Route";
+import { Step } from "./Step";
+import { PersistenceManager } from "./PersistenceManager";
+import { SessionManager } from "./SessionManager";
+import { RoutingEngine } from "./RoutingEngine";
+import { ToolManager } from "./ToolManager";
+/**
+ * Main Agent class with generic context and data support
+ */
+export declare class Agent<TContext = any, TData = any> {
+    private readonly options;
+    private terms;
+    private guidelines;
+    private tools;
+    private routes;
+    private context;
+    private persistenceManager;
+    private routingEngine;
+    private responseModal;
+    private currentSession?;
+    private knowledgeBase;
+    private schema?;
+    private collectedData;
+    /** Public session manager for easy session management */
+    session: SessionManager<TData>;
+    /** Public tool manager for simplified tool creation and management */
+    tool: ToolManager<TContext, TData>;
+    constructor(options: AgentOptions<TContext, TData>);
+    /**
+     * Validate the agent-level schema structure
+     * @private
+     */
+    private validateSchema;
+    /**
+     * Validate data against the agent-level schema
+     */
+    validateData(data: Partial<TData>): ValidationResult;
+    /**
+     * Check if a field is valid according to the agent schema
+     * @param field - The field key to validate
+     * @returns true if field exists in schema or no schema is defined, false otherwise
+     */
+    isValidSchemaField(field: keyof TData): boolean;
+    /**
+     * Get the current collected data
+     */
+    getCollectedData(): Partial<TData>;
+    /**
+     * Update collected data with validation
+     */
+    updateCollectedData(updates: Partial<TData>): Promise<void>;
+    /**
+     * Get agent name
+     */
+    get name(): string;
+    /**
+     * Get agent description
+     */
+    get description(): string | undefined;
+    /**
+     * Get agent goal
+     */
+    get goal(): string | undefined;
+    /**
+     * Get agent identity
+     */
+    get identity(): Template<TContext> | undefined;
+    /**
+     * Create a new route (journey) using agent-level data type
+     */
+    createRoute(options: RouteOptions<TContext, TData>): Route<TContext, TData>;
+    /**
+     * Create a domain term for the glossary
+     */
+    createTerm(term: Term<TContext, TData>): this;
+    /**
+     * Create a behavioral guideline
+     */
+    createGuideline(guideline: Guideline<TContext, TData>): this;
+    /**
+     * Add a tool to the agent using the unified Tool interface
+     * Creates and adds the tool to agent scope in one operation (BREAKING CHANGE: replaces createTool)
+     */
+    addTool<TResult = any>(tool: Tool<TContext, TData, TResult>): this;
+    /**
+     * Register a tool at the agent level (legacy method for backward compatibility)
+     * @deprecated Use addTool() with Tool interface instead
+     */
+    createTool<TResult = any>(tool: Tool<TContext, TData, TResult>): this;
+    /**
+     * Register multiple tools at the agent level
+     */
+    registerTools<TResult = any>(tools: Tool<TContext, TData, TResult>[]): this;
+    /**
+     * Update the agent's context
+     * Triggers both agent-level and route-specific onContextUpdate lifecycle hooks if configured
+     */
+    updateContext(updates: Partial<TContext>): Promise<void>;
+    /**
+     * Update collected data in session with lifecycle hook support
+     * Triggers both agent-level and route-specific onDataUpdate lifecycle hooks if configured
+     * @internal
+     */
+    private updateData;
+    /**
+     * Get current context (fetches from provider if configured)
+     */
+    getContext(): Promise<TContext | undefined>;
+    /**
+     * Get current schema
+     */
+    getSchema(): StructuredSchema | undefined;
+    /**
+     * Generate a response based on history and context as a stream
+     */
+    respondStream(params: RespondParams<TContext, TData>): AsyncGenerator<AgentResponseStreamChunk<TData>>;
+    /**
+     * Generate a response based on history and context
+     */
+    respond(params: RespondParams<TContext, TData>): Promise<AgentResponse<TData>>;
+    /**
+     * Get all routes
+     */
+    getRoutes(): Route<TContext, TData>[];
+    /**
+     * Get agent options
+     * @internal Used by ResponseModal
+     */
+    getAgentOptions(): AgentOptions<TContext, TData>;
+    /**
+     * Get routing engine
+     * @internal Used by ResponseModal
+     */
+    getRoutingEngine(): RoutingEngine<TContext, TData>;
+    /**
+     * Get the updateData method bound to this agent
+     * @internal Used by ResponseModal
+     */
+    getUpdateDataMethod(): (session: SessionState<TData>, dataUpdate: Partial<TData>) => Promise<SessionState<TData>>;
+    /**
+     * Get all terms
+     */
+    getTerms(): Term<TContext, TData>[];
+    /**
+     * Get all tools
+     */
+    getTools(): Tool<TContext, TData>[];
+    /**
+     * Get all guidelines
+     */
+    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 the agent's knowledge base
+     */
+    getKnowledgeBase(): Record<string, unknown>;
+    /**
+     * Get the persistence manager (if configured)
+     */
+    getPersistenceManager(): PersistenceManager<TData> | undefined;
+    /**
+     * Check if persistence is enabled
+     */
+    hasPersistence(): boolean;
+    /**
+     * Set the current session for convenience methods
+     * @param session - Session step to use for subsequent calls
+     */
+    setCurrentSession(session: SessionState): void;
+    /**
+     * Get the current session (if set)
+     */
+    getCurrentSession(): SessionState | undefined;
+    /**
+     * Execute a prepare or finalize function/tool
+     * @internal Used by ResponseModal
+     */
+    executePrepareFinalize(prepareOrFinalize: string | Tool<TContext, TData> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>) | undefined, context: TContext, data?: Partial<TData>, route?: Route<TContext, TData>, step?: Step<TContext, TData>): Promise<void>;
+    /**
+     * Clear the current session
+     */
+    clearCurrentSession(): void;
+    /**
+     * Sync session data to agent collected data
+     * @internal Used to keep agent and session data in sync
+     */
+    private syncSessionDataToCollectedData;
+    /**
+     * Get collected data from current session or agent-level collected data
+     * @param routeId - Optional route ID to get data for (uses current route if not provided)
+     * @returns The collected data from the current session or agent-level data
+     */
+    getData(): Partial<TData>;
+    /**
+     * Manually transition to a different route
+     * Sets a pending transition that will be executed on the next respond() call
+     *
+     * @param routeIdOrTitle - Route ID or title to transition to
+     * @param session - Session step to update (uses current session if not provided)
+     * @param condition - Optional AI-evaluated condition for the transition
+     * @returns Updated session with pending transition
+     *
+     * @example
+     * // After route completes
+     * if (response.isRouteComplete && response.session) {
+     *   const updatedSession = agent.nextStepRoute("feedback-collection", response.session);
+     *   // Next respond() call will automatically transition to feedback route
+     *   const nextResponse = await agent.respond({ history, session: updatedSession });
+     * }
+     */
+    nextStepRoute(routeIdOrTitle: string, session?: SessionState<TData>, condition?: Template<TContext, TData>, history?: Event[]): Promise<SessionState<TData>>;
+    /**
+     * Simplified respond method using SessionManager
+     * Automatically manages conversation history through the session
+     */
+    chat(message?: string, options?: GenerateOptions<TContext>): Promise<AgentResponse<TData>>;
+    /**
+     * Modern streaming API - simple interface like chat() but returns a stream
+     * Automatically manages conversation history through the session
+     */
+    stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>;
+}
+//# sourceMappingURL=Agent.d.ts.map

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

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