overai 1.4.0

package/dist/agent/enhanced.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * Enhanced Agent - Agent with session management, provider abstraction, and tool support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnhancedAgent = void 0;
+const backend_resolver_1 = require("../llm/backend-resolver");
+const session_1 = require("../session");
+const decorator_1 = require("../tools/decorator");
+const logger_1 = require("../utils/logger");
+/**
+ * Enhanced Agent with full feature support
+ */
+class EnhancedAgent {
+    constructor(config) {
+        this.provider = null;
+        this.providerPromise = null;
+        this.name = config.name || `Agent_${Math.random().toString(36).substr(2, 9)}`;
+        this.instructions = config.instructions;
+        this.verbose = config.verbose ?? true;
+        this.stream = config.stream ?? true;
+        this.maxToolCalls = config.maxToolCalls ?? 10;
+        this.temperature = config.temperature ?? 0.7;
+        this.maxTokens = config.maxTokens;
+        this.outputSchema = config.outputSchema;
+        // Store model string for lazy provider initialization
+        this.llmModel = config.llm || 'openai/gpt-4o-mini';
+        // Initialize session
+        if (config.session) {
+            this.session = config.session;
+        }
+        else if (config.sessionId) {
+            this.session = (0, session_1.getSessionManager)().getOrCreate(config.sessionId);
+        }
+        else {
+            this.session = (0, session_1.getSessionManager)().create();
+        }
+        this.sessionId = this.session.id;
+        // Initialize tool registry
+        this.toolRegistry = new decorator_1.ToolRegistry();
+        if (config.tools) {
+            this.registerTools(config.tools);
+        }
+        logger_1.Logger.setVerbose(this.verbose);
+    }
+    /**
+     * Get the LLM provider (lazy initialization with AI SDK backend)
+     */
+    async getProvider() {
+        if (this.provider) {
+            return this.provider;
+        }
+        if (!this.providerPromise) {
+            this.providerPromise = (async () => {
+                const result = await (0, backend_resolver_1.resolveBackend)(this.llmModel, {
+                    attribution: {
+                        agentId: this.name,
+                        sessionId: this.sessionId,
+                    },
+                });
+                this.provider = result.provider;
+                return result.provider;
+            })();
+        }
+        return this.providerPromise;
+    }
+    registerTools(tools) {
+        if (!tools)
+            return;
+        for (const t of tools) {
+            if (t instanceof decorator_1.FunctionTool) {
+                this.toolRegistry.register(t);
+            }
+            else if (typeof t === 'function') {
+                // Convert function to tool
+                const funcName = t.name || `function_${Math.random().toString(36).substr(2, 9)}`;
+                this.toolRegistry.register((0, decorator_1.tool)({
+                    name: funcName,
+                    description: `Function ${funcName}`,
+                    execute: t,
+                }));
+            }
+            else if (typeof t === 'object' && 'execute' in t) {
+                // Tool config object
+                this.toolRegistry.register((0, decorator_1.tool)({
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                    execute: t.execute,
+                }));
+            }
+        }
+    }
+    /**
+     * Add a tool to the agent
+     */
+    addTool(t) {
+        if (t instanceof decorator_1.FunctionTool) {
+            this.toolRegistry.register(t);
+        }
+        else {
+            this.toolRegistry.register((0, decorator_1.tool)({
+                name: t.name,
+                description: t.description,
+                parameters: t.parameters,
+                execute: t.execute,
+            }));
+        }
+        return this;
+    }
+    /**
+     * Get all registered tools
+     */
+    getTools() {
+        return this.toolRegistry.list();
+    }
+    /**
+     * Chat with the agent
+     */
+    async chat(prompt, options = {}) {
+        const run = this.session.createRun().start();
+        const trace = run.createTrace({ name: 'chat' }).start();
+        try {
+            // Add user message to session
+            this.session.addMessage({ role: 'user', content: prompt });
+            // Build messages array
+            const messages = [
+                { role: 'system', content: this.instructions },
+                ...this.session.getMessagesForLLM(),
+            ];
+            // Get tool definitions
+            const tools = this.toolRegistry.list().length > 0
+                ? this.toolRegistry.getDefinitions()
+                : undefined;
+            let result;
+            let fullText = '';
+            let allToolCalls = [];
+            let iterations = 0;
+            // Tool calling loop
+            while (iterations < this.maxToolCalls) {
+                iterations++;
+                if (options.stream && !tools && options.onToken) {
+                    // Streaming without tools
+                    const provider = await this.getProvider();
+                    const stream = await provider.streamText({
+                        messages,
+                        temperature: options.temperature ?? this.temperature,
+                        maxTokens: options.maxTokens ?? this.maxTokens,
+                        onToken: options.onToken,
+                    });
+                    let usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+                    for await (const chunk of stream) {
+                        if (chunk.text)
+                            fullText += chunk.text;
+                        if (chunk.usage)
+                            usage = { ...usage, ...chunk.usage };
+                    }
+                    result = {
+                        text: fullText,
+                        usage,
+                        finishReason: 'stop',
+                    };
+                    break;
+                }
+                else if (options.outputSchema) {
+                    // Structured output
+                    const provider = await this.getProvider();
+                    const objResult = await provider.generateObject({
+                        messages,
+                        schema: options.outputSchema ?? this.outputSchema,
+                        temperature: options.temperature ?? this.temperature,
+                        maxTokens: options.maxTokens ?? this.maxTokens,
+                    });
+                    result = {
+                        text: JSON.stringify(objResult.object),
+                        usage: objResult.usage,
+                        finishReason: 'stop',
+                    };
+                    fullText = result.text;
+                    break;
+                }
+                else {
+                    // Regular generation with potential tool calls
+                    const provider = await this.getProvider();
+                    result = await provider.generateText({
+                        messages,
+                        temperature: options.temperature ?? this.temperature,
+                        maxTokens: options.maxTokens ?? this.maxTokens,
+                        tools,
+                    });
+                    if (result.toolCalls && result.toolCalls.length > 0) {
+                        allToolCalls.push(...result.toolCalls);
+                        // Add assistant message with tool calls
+                        messages.push({
+                            role: 'assistant',
+                            content: result.text || null,
+                            tool_calls: result.toolCalls,
+                        });
+                        // Execute tool calls
+                        for (const tc of result.toolCalls) {
+                            const toolTrace = trace.createChild({ name: `tool:${tc.function.name}` }).start();
+                            try {
+                                const toolFn = this.toolRegistry.get(tc.function.name);
+                                if (!toolFn) {
+                                    throw new Error(`Tool '${tc.function.name}' not found`);
+                                }
+                                const args = JSON.parse(tc.function.arguments);
+                                const toolResult = await toolFn.execute(args, {
+                                    agentName: this.name,
+                                    sessionId: this.sessionId,
+                                    runId: run.id,
+                                });
+                                const resultStr = typeof toolResult === 'string'
+                                    ? toolResult
+                                    : JSON.stringify(toolResult);
+                                messages.push({
+                                    role: 'tool',
+                                    content: resultStr,
+                                    tool_call_id: tc.id,
+                                });
+                                toolTrace.complete({ result: resultStr });
+                            }
+                            catch (error) {
+                                messages.push({
+                                    role: 'tool',
+                                    content: `Error: ${error.message}`,
+                                    tool_call_id: tc.id,
+                                });
+                                toolTrace.fail(error);
+                            }
+                        }
+                        // Continue loop to get final response
+                        continue;
+                    }
+                    // No tool calls, we have our final response
+                    fullText = result.text;
+                    break;
+                }
+            }
+            // Add assistant message to session
+            this.session.addMessage({
+                role: 'assistant',
+                content: fullText,
+                tool_calls: allToolCalls.length > 0 ? allToolCalls : undefined,
+            });
+            trace.complete({ responseLength: fullText.length });
+            run.complete();
+            // Parse structured output if schema was provided
+            let structured;
+            if (options.outputSchema) {
+                try {
+                    structured = JSON.parse(fullText);
+                }
+                catch {
+                    // Not valid JSON
+                }
+            }
+            return {
+                text: fullText,
+                structured,
+                toolCalls: allToolCalls.length > 0 ? allToolCalls : undefined,
+                usage: result.usage,
+                runId: run.id,
+                sessionId: this.sessionId,
+            };
+        }
+        catch (error) {
+            trace.fail(error);
+            run.fail(error);
+            throw error;
+        }
+    }
+    /**
+     * Start method for compatibility
+     */
+    async start(prompt, options) {
+        const result = await this.chat(prompt, options);
+        return result.text;
+    }
+    /**
+     * Get the session
+     */
+    getSession() {
+        return this.session;
+    }
+    /**
+     * Clear conversation history
+     */
+    clearHistory() {
+        this.session.clearMessages();
+    }
+}
+exports.EnhancedAgent = EnhancedAgent;

package/dist/agent/handoff.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Agent Handoff - Transfer conversations between agents
+ */
+import type { EnhancedAgent } from './enhanced';
+export interface HandoffConfig {
+    agent: EnhancedAgent;
+    name?: string;
+    description?: string;
+    condition?: (context: HandoffContext) => boolean;
+    transformContext?: (messages: any[]) => any[];
+}
+export interface HandoffContext {
+    messages: any[];
+    lastMessage: string;
+    topic?: string;
+    metadata?: Record<string, any>;
+}
+export interface HandoffResult {
+    handedOffTo: string;
+    response: string;
+    context: HandoffContext;
+}
+/**
+ * Handoff class - Represents a handoff target
+ */
+export declare class Handoff {
+    readonly targetAgent: EnhancedAgent;
+    readonly name: string;
+    readonly description: string;
+    readonly condition?: (context: HandoffContext) => boolean;
+    readonly transformContext?: (messages: any[]) => any[];
+    constructor(config: HandoffConfig);
+    /**
+     * Check if handoff should be triggered
+     */
+    shouldTrigger(context: HandoffContext): boolean;
+    /**
+     * Execute the handoff
+     */
+    execute(context: HandoffContext): Promise<HandoffResult>;
+    /**
+     * Get tool definition for LLM
+     */
+    getToolDefinition(): {
+        name: string;
+        description: string;
+        parameters: any;
+    };
+}
+/**
+ * Create a handoff configuration
+ */
+export declare function handoff(config: HandoffConfig): Handoff;
+/**
+ * Handoff filters - Common condition functions
+ */
+export declare const handoffFilters: {
+    /**
+     * Trigger handoff based on topic keywords
+     */
+    topic: (keywords: string | string[]) => (context: HandoffContext) => boolean;
+    /**
+     * Trigger handoff based on metadata
+     */
+    metadata: (key: string, value: any) => (context: HandoffContext) => boolean;
+    /**
+     * Always trigger
+     */
+    always: () => () => boolean;
+    /**
+     * Never trigger (manual only)
+     */
+    never: () => () => boolean;
+    /**
+     * Combine multiple conditions with AND
+     */
+    and: (...conditions: Array<(context: HandoffContext) => boolean>) => (context: HandoffContext) => boolean;
+    /**
+     * Combine multiple conditions with OR
+     */
+    or: (...conditions: Array<(context: HandoffContext) => boolean>) => (context: HandoffContext) => boolean;
+};

package/dist/agent/handoff.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Agent Handoff - Transfer conversations between agents
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handoffFilters = exports.Handoff = void 0;
+exports.handoff = handoff;
+/**
+ * Handoff class - Represents a handoff target
+ */
+class Handoff {
+    constructor(config) {
+        this.targetAgent = config.agent;
+        this.name = config.name || `handoff_to_${config.agent.name}`;
+        this.description = config.description || `Transfer conversation to ${config.agent.name}`;
+        this.condition = config.condition;
+        this.transformContext = config.transformContext;
+    }
+    /**
+     * Check if handoff should be triggered
+     */
+    shouldTrigger(context) {
+        if (this.condition) {
+            return this.condition(context);
+        }
+        return true;
+    }
+    /**
+     * Execute the handoff
+     */
+    async execute(context) {
+        let messages = context.messages;
+        if (this.transformContext) {
+            messages = this.transformContext(messages);
+        }
+        // Transfer context to target agent
+        const response = await this.targetAgent.chat(context.lastMessage);
+        return {
+            handedOffTo: this.targetAgent.name,
+            response: response.text,
+            context: {
+                ...context,
+                messages,
+            },
+        };
+    }
+    /**
+     * Get tool definition for LLM
+     */
+    getToolDefinition() {
+        return {
+            name: this.name,
+            description: this.description,
+            parameters: {
+                type: 'object',
+                properties: {
+                    reason: {
+                        type: 'string',
+                        description: 'Reason for the handoff',
+                    },
+                },
+                required: [],
+            },
+        };
+    }
+}
+exports.Handoff = Handoff;
+/**
+ * Create a handoff configuration
+ */
+function handoff(config) {
+    return new Handoff(config);
+}
+/**
+ * Handoff filters - Common condition functions
+ */
+exports.handoffFilters = {
+    /**
+     * Trigger handoff based on topic keywords
+     */
+    topic: (keywords) => {
+        const keywordList = Array.isArray(keywords) ? keywords : [keywords];
+        return (context) => {
+            const lastMessage = context.lastMessage.toLowerCase();
+            return keywordList.some(kw => lastMessage.includes(kw.toLowerCase()));
+        };
+    },
+    /**
+     * Trigger handoff based on metadata
+     */
+    metadata: (key, value) => {
+        return (context) => {
+            return context.metadata?.[key] === value;
+        };
+    },
+    /**
+     * Always trigger
+     */
+    always: () => {
+        return () => true;
+    },
+    /**
+     * Never trigger (manual only)
+     */
+    never: () => {
+        return () => false;
+    },
+    /**
+     * Combine multiple conditions with AND
+     */
+    and: (...conditions) => {
+        return (context) => {
+            return conditions.every(cond => cond(context));
+        };
+    },
+    /**
+     * Combine multiple conditions with OR
+     */
+    or: (...conditions) => {
+        return (context) => {
+            return conditions.some(cond => cond(context));
+        };
+    },
+};

package/dist/agent/image.d.ts

@@ -0,0 +1,57 @@
+/**
+ * ImageAgent - Agent for image generation and analysis
+ */
+export interface ImageGenerationConfig {
+    prompt: string;
+    size?: '256x256' | '512x512' | '1024x1024' | '1792x1024' | '1024x1792';
+    quality?: 'standard' | 'hd';
+    style?: 'vivid' | 'natural';
+    n?: number;
+}
+export interface ImageAnalysisConfig {
+    imageUrl: string;
+    prompt?: string;
+    detail?: 'low' | 'high' | 'auto';
+}
+export interface ImageAgentConfig {
+    name?: string;
+    llm?: string;
+    imageModel?: string;
+    verbose?: boolean;
+}
+/**
+ * ImageAgent - Agent for image generation and analysis
+ */
+export declare class ImageAgent {
+    readonly name: string;
+    private provider;
+    private providerPromise;
+    private llmModel;
+    private imageModel;
+    private verbose;
+    constructor(config?: ImageAgentConfig);
+    /**
+     * Get the LLM provider (lazy initialization with AI SDK backend)
+     */
+    private getProvider;
+    /**
+     * Analyze an image
+     */
+    analyze(config: ImageAnalysisConfig): Promise<string>;
+    /**
+     * Generate an image (requires OpenAI DALL-E)
+     */
+    generate(config: ImageGenerationConfig): Promise<string[]>;
+    /**
+     * Chat with image context
+     */
+    chat(prompt: string, imageUrl?: string): Promise<string>;
+    /**
+     * Compare two images
+     */
+    compare(imageUrl1: string, imageUrl2: string, prompt?: string): Promise<string>;
+}
+/**
+ * Create an ImageAgent
+ */
+export declare function createImageAgent(config?: ImageAgentConfig): ImageAgent;

package/dist/agent/image.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * ImageAgent - Agent for image generation and analysis
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImageAgent = void 0;
+exports.createImageAgent = createImageAgent;
+const backend_resolver_1 = require("../llm/backend-resolver");
+/**
+ * ImageAgent - Agent for image generation and analysis
+ */
+class ImageAgent {
+    constructor(config = {}) {
+        this.provider = null;
+        this.providerPromise = null;
+        this.name = config.name || `ImageAgent_${Math.random().toString(36).substr(2, 9)}`;
+        this.llmModel = config.llm || 'openai/gpt-4o-mini';
+        this.imageModel = config.imageModel || 'dall-e-3';
+        this.verbose = config.verbose ?? false;
+    }
+    /**
+     * Get the LLM provider (lazy initialization with AI SDK backend)
+     */
+    async getProvider() {
+        if (this.provider) {
+            return this.provider;
+        }
+        if (!this.providerPromise) {
+            this.providerPromise = (async () => {
+                const result = await (0, backend_resolver_1.resolveBackend)(this.llmModel, {
+                    attribution: { agentId: this.name },
+                });
+                this.provider = result.provider;
+                return result.provider;
+            })();
+        }
+        return this.providerPromise;
+    }
+    /**
+     * Analyze an image
+     */
+    async analyze(config) {
+        const prompt = config.prompt || 'Describe this image in detail.';
+        const messages = [
+            {
+                role: 'user',
+                content: [
+                    { type: 'text', text: prompt },
+                    {
+                        type: 'image_url',
+                        image_url: {
+                            url: config.imageUrl,
+                            detail: config.detail || 'auto'
+                        }
+                    }
+                ]
+            }
+        ];
+        const provider = await this.getProvider();
+        const result = await provider.generateText({ messages });
+        if (this.verbose) {
+            console.log(`[ImageAgent] Analysis: ${result.text.substring(0, 100)}...`);
+        }
+        return result.text;
+    }
+    /**
+     * Generate an image (requires OpenAI DALL-E)
+     */
+    async generate(config) {
+        // This would require direct OpenAI API call for image generation
+        // For now, return a placeholder
+        if (this.verbose) {
+            console.log(`[ImageAgent] Generating image: ${config.prompt}`);
+        }
+        throw new Error('Image generation requires direct OpenAI API integration. Use the OpenAI SDK directly for DALL-E.');
+    }
+    /**
+     * Chat with image context
+     */
+    async chat(prompt, imageUrl) {
+        if (imageUrl) {
+            return this.analyze({ imageUrl, prompt });
+        }
+        const provider = await this.getProvider();
+        const result = await provider.generateText({
+            messages: [{ role: 'user', content: prompt }]
+        });
+        return result.text;
+    }
+    /**
+     * Compare two images
+     */
+    async compare(imageUrl1, imageUrl2, prompt) {
+        const comparePrompt = prompt || 'Compare these two images and describe the differences and similarities.';
+        const messages = [
+            {
+                role: 'user',
+                content: [
+                    { type: 'text', text: comparePrompt },
+                    { type: 'image_url', image_url: { url: imageUrl1 } },
+                    { type: 'image_url', image_url: { url: imageUrl2 } }
+                ]
+            }
+        ];
+        const provider = await this.getProvider();
+        const result = await provider.generateText({ messages });
+        return result.text;
+    }
+}
+exports.ImageAgent = ImageAgent;
+/**
+ * Create an ImageAgent
+ */
+function createImageAgent(config) {
+    return new ImageAgent(config);
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Agent Module - Core agent classes for PraisonAI
+ *
+ * The primary exports are:
+ * - Agent: Single agent with instructions, tools, and optional persistence
+ * - Agents: Multi-agent orchestration (alias for PraisonAIAgents)
+ * - Router: Simplified keyword/pattern-based routing
+ * - Workflow: Step-based workflow execution (from workflows module)
+ */
+export { Agent, PraisonAIAgents, Agents } from './simple';
+export type { SimpleAgentConfig, PraisonAIAgentsConfig } from './simple';
+export { Router, RouterAgent, createRouter, routeConditions } from './router';
+export type { RouterConfig, RouteConfig, RouteContext, SimpleRouterConfig, SimpleRouteConfig } from './router';
+export { Task } from './types';
+export type { TaskConfig, AgentConfig as TaskAgentConfig } from './types';
+/**
+ * @deprecated Task mode is no longer needed. Use Agent with role/goal/backstory instead.
+ */
+export declare function setTaskMode(enabled: boolean): void;