@falai/agent 0.8.1 → 0.9.0-alpha-2

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

@@ -0,0 +1,223 @@
+/**
+ * Core Agent implementation
+ */
+import type { AgentOptions, Term, Guideline, Tool, Event, RouteOptions, SessionState, Template, StepRef, History, AgentResponseStreamChunk, AgentResponse, StructuredSchema, ValidationResult } from "../types";
+import { Route } from "./Route";
+import { PersistenceManager } from "./PersistenceManager";
+import { SessionManager } from "./SessionManager";
+/**
+ * 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 responseEngine;
+    private responsePipeline;
+    private currentSession?;
+    private knowledgeBase;
+    private schema?;
+    private collectedData;
+    /** Public session manager for easy session management */
+    session: SessionManager<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;
+    /**
+     * Register a tool at the agent level
+     */
+    createTool(tool: Tool<TContext, TData, unknown[], unknown>): this;
+    /**
+     * Register multiple tools at the agent level
+     */
+    registerTools(tools: Tool<TContext, TData, unknown[], unknown>[]): 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: {
+        history: History;
+        step?: StepRef;
+        session?: SessionState<TData>;
+        contextOverride?: Partial<TContext>;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentResponseStreamChunk<TData>>;
+    /**
+     * Generate a response based on history and context
+     */
+    respond(params: {
+        history: History;
+        step?: StepRef;
+        session?: SessionState<TData>;
+        contextOverride?: Partial<TContext>;
+        signal?: AbortSignal;
+    }): Promise<AgentResponse<TData>>;
+    /**
+     * Get all routes
+     */
+    getRoutes(): Route<TContext, TData>[];
+    /**
+     * Get all terms
+     */
+    getTerms(): Term<TContext, TData>[];
+    /**
+     * Get all tools
+     */
+    getTools(): Tool<TContext, TData, unknown[], unknown>[];
+    /**
+     * Find an available tool by name for the given route
+     * Route-level tools take precedence over agent-level tools
+     * @private
+     */
+    private findAvailableTool;
+    /**
+     * Collect all available tools for the given route and step context
+     * @private
+     */
+    private collectAvailableTools;
+    /**
+     * Execute a prepare or finalize function/tool
+     * @private
+     */
+    private executePrepareFinalize;
+    /**
+     * Get all guidelines
+     */
+    getGuidelines(): Guideline<TContext, TData>[];
+    /**
+     * Get the agent's knowledge base
+     */
+    getKnowledgeBase(): Record<string, unknown>;
+    /**
+     * Merge terms with route-specific taking precedence on conflicts
+     * @private
+     */
+    private mergeTerms;
+    /**
+     * 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;
+    /**
+     * Clear the current session
+     */
+    clearCurrentSession(): void;
+    /**
+     * 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?: {
+        history?: History;
+        contextOverride?: Partial<TContext>;
+        signal?: AbortSignal;
+    }): Promise<AgentResponse<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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"}