overai 1.4.0

package/dist/agent/simple.d.ts

@@ -0,0 +1,289 @@
+import type { DbAdapter } from '../db/types';
+import type { LLMProvider } from '../llm/providers/types';
+/**
+ * Agent Configuration
+ *
+ * The Agent class is the primary entry point for PraisonAI.
+ * It supports both simple instruction-based agents and advanced configurations.
+ *
+ * @example Simple usage (3 lines)
+ * ```typescript
+ * import { Agent } from 'praisonai';
+ * const agent = new Agent({ instructions: "You are helpful" });
+ * await agent.chat("Hello!");
+ * ```
+ *
+ * @example With tools (5 lines)
+ * ```typescript
+ * const getWeather = (city: string) => `Weather in ${city}: 20°C`;
+ * const agent = new Agent({
+ *   instructions: "You provide weather info",
+ *   tools: [getWeather]
+ * });
+ * await agent.chat("Weather in Paris?");
+ * ```
+ *
+ * @example With persistence (4 lines)
+ * ```typescript
+ * import { Agent, db } from 'praisonai';
+ * const agent = new Agent({
+ *   instructions: "You are helpful",
+ *   db: db("sqlite:./data.db"),
+ *   sessionId: "my-session"
+ * });
+ * await agent.chat("Hello!");
+ * ```
+ */
+export interface SimpleAgentConfig {
+    /** Agent instructions/system prompt (required) */
+    instructions: string;
+    /** Agent name (auto-generated if not provided) */
+    name?: string;
+    /** Enable verbose logging (default: true) */
+    verbose?: boolean;
+    /** Enable pretty output formatting */
+    pretty?: boolean;
+    /**
+     * LLM model to use. Accepts:
+     * - Model name: "gpt-4o-mini", "claude-3-sonnet"
+     * - Provider/model: "openai/gpt-4o", "anthropic/claude-3"
+     * Default: "gpt-4o-mini"
+     */
+    llm?: string;
+    /** Enable markdown formatting in responses */
+    markdown?: boolean;
+    /** Enable streaming responses (default: true) */
+    stream?: boolean;
+    /**
+     * Tools available to the agent.
+     * Can be plain functions (auto-schema) or OpenAI tool definitions.
+     */
+    tools?: any[] | Function[];
+    /** Map of tool function implementations */
+    toolFunctions?: Record<string, Function>;
+    /** Database adapter for persistence */
+    db?: DbAdapter;
+    /** Session ID for conversation persistence (auto-generated if not provided) */
+    sessionId?: string;
+    /** Run ID for tracing (auto-generated if not provided) */
+    runId?: string;
+    /** Max messages to restore from history (default: 100) */
+    historyLimit?: number;
+    /** Auto-restore conversation history from db (default: true) */
+    autoRestore?: boolean;
+    /** Auto-persist messages to db (default: true) */
+    autoPersist?: boolean;
+    /** Enable caching of responses */
+    cache?: boolean;
+    /** Cache TTL in seconds (default: 3600) */
+    cacheTTL?: number;
+    /** Enable telemetry tracking (default: false, opt-in) */
+    telemetry?: boolean;
+    /** Agent role (advanced mode) */
+    role?: string;
+    /** Agent goal (advanced mode) */
+    goal?: string;
+    /** Agent backstory (advanced mode) */
+    backstory?: string;
+}
+export declare class Agent {
+    private instructions;
+    name: string;
+    private verbose;
+    private pretty;
+    private llm;
+    private markdown;
+    private stream;
+    private llmService;
+    private tools?;
+    private toolFunctions;
+    private dbAdapter?;
+    private sessionId;
+    private runId;
+    private messages;
+    private dbInitialized;
+    private historyLimit;
+    private autoRestore;
+    private autoPersist;
+    private cache;
+    private cacheTTL;
+    private responseCache;
+    private telemetryEnabled;
+    private _backend;
+    private _backendPromise;
+    private _backendSource;
+    private _useAISDKBackend;
+    constructor(config: SimpleAgentConfig);
+    /**
+     * Generate a unique session ID based on current hour, agent name, and random suffix
+     */
+    private generateSessionId;
+    /**
+     * Initialize DB session - restore history on first chat (lazy)
+     */
+    private initDbSession;
+    /**
+     * Get cached response if available and not expired
+     */
+    private getCachedResponse;
+    /**
+     * Cache a response
+     */
+    private cacheResponse;
+    private createSystemPrompt;
+    /**
+     * Register a tool function that can be called by the model
+     * @param name Function name
+     * @param fn Function implementation
+     */
+    registerToolFunction(name: string, fn: Function): void;
+    /**
+     * Check if a tool definition exists for the given function name
+     * @param name Function name
+     * @returns True if a tool definition exists
+     */
+    private hasToolDefinition;
+    /**
+     * Auto-generate a tool definition based on the function
+     * @param name Function name
+     * @param func Function implementation
+     */
+    private addAutoGeneratedToolDefinition;
+    /**
+     * Process tool calls from the model
+     * @param toolCalls Tool calls from the model
+     * @returns Array of tool results
+     */
+    private processToolCalls;
+    start(prompt: string, previousResult?: string): Promise<string>;
+    chat(prompt: string, previousResult?: string): Promise<string>;
+    execute(previousResult?: string): Promise<string>;
+    /**
+     * Persist a message to the database
+     */
+    private persistMessage;
+    /**
+     * Get the session ID for this agent
+     */
+    getSessionId(): string;
+    /**
+     * Get the run ID for this agent
+     */
+    getRunId(): string;
+    getResult(): string | null;
+    getInstructions(): string;
+    /**
+     * Get conversation history
+     */
+    getHistory(): Array<{
+        role: string;
+        content: string | null;
+    }>;
+    /**
+     * Clear conversation history (in memory and optionally in DB)
+     */
+    clearHistory(clearDb?: boolean): Promise<void>;
+    /**
+     * Clear response cache
+     */
+    clearCache(): void;
+    /**
+     * Get the resolved backend (AI SDK preferred, native fallback)
+     * Lazy initialization - backend is only resolved on first use
+     */
+    getBackend(): Promise<LLMProvider>;
+    /**
+     * Get the backend source (ai-sdk, native, custom, or legacy)
+     */
+    getBackendSource(): 'ai-sdk' | 'native' | 'custom' | 'legacy';
+    /**
+     * Embed text using AI SDK (preferred) or native provider
+     *
+     * @param text - Text to embed (string or array of strings)
+     * @param options - Embedding options
+     * @returns Embedding vector(s)
+     *
+     * @example Single text
+     * ```typescript
+     * const embedding = await agent.embed("Hello world");
+     * ```
+     *
+     * @example Multiple texts
+     * ```typescript
+     * const embeddings = await agent.embed(["Hello", "World"]);
+     * ```
+     */
+    embed(text: string | string[], options?: {
+        model?: string;
+    }): Promise<number[] | number[][]>;
+    /**
+     * Get the model string for this agent
+     */
+    getModel(): string;
+}
+/**
+ * Configuration for multi-agent orchestration
+ */
+export interface PraisonAIAgentsConfig {
+    agents: Agent[];
+    tasks?: string[];
+    verbose?: boolean;
+    pretty?: boolean;
+    process?: 'sequential' | 'parallel';
+}
+/**
+ * Multi-agent orchestration class
+ *
+ * @example Simple array syntax
+ * ```typescript
+ * import { Agent, Agents } from 'praisonai';
+ *
+ * const researcher = new Agent({ instructions: "Research the topic" });
+ * const writer = new Agent({ instructions: "Write based on research" });
+ *
+ * const agents = new Agents([researcher, writer]);
+ * await agents.start();
+ * ```
+ *
+ * @example Config object syntax
+ * ```typescript
+ * const agents = new Agents({
+ *   agents: [researcher, writer],
+ *   process: 'parallel'
+ * });
+ * ```
+ */
+export declare class PraisonAIAgents {
+    private agents;
+    private tasks;
+    private verbose;
+    private pretty;
+    private process;
+    /**
+     * Create a multi-agent orchestration
+     * @param configOrAgents - Either an array of agents or a config object
+     */
+    constructor(configOrAgents: PraisonAIAgentsConfig | Agent[]);
+    private generateTasks;
+    private executeSequential;
+    start(): Promise<string[]>;
+    chat(): Promise<string[]>;
+}
+/**
+ * Agents - Alias for PraisonAIAgents
+ *
+ * This is the recommended class name for multi-agent orchestration.
+ * PraisonAIAgents is kept for backward compatibility.
+ *
+ * @example
+ * ```typescript
+ * import { Agent, Agents } from 'praisonai';
+ *
+ * const agents = new Agents([
+ *   new Agent({ instructions: "Research the topic" }),
+ *   new Agent({ instructions: "Write based on research" })
+ * ]);
+ * await agents.start();
+ * ```
+ */
+export declare const Agents: typeof PraisonAIAgents;