overai 1.4.0

package/dist/telemetry/index.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Telemetry - Usage tracking and analytics
+ */
+export interface TelemetryEvent {
+    name: string;
+    timestamp: number;
+    properties?: Record<string, any>;
+    userId?: string;
+    sessionId?: string;
+}
+export interface TelemetryConfig {
+    enabled?: boolean;
+    endpoint?: string;
+    batchSize?: number;
+    flushInterval?: number;
+}
+/**
+ * Telemetry collector for tracking usage
+ */
+export declare class TelemetryCollector {
+    private events;
+    private enabled;
+    private endpoint?;
+    private batchSize;
+    private flushInterval;
+    private flushTimer?;
+    private userId?;
+    private sessionId;
+    constructor(config?: TelemetryConfig);
+    private checkEnabled;
+    /**
+     * Track an event
+     */
+    track(name: string, properties?: Record<string, any>): void;
+    /**
+     * Track feature usage
+     */
+    trackFeatureUsage(feature: string, metadata?: Record<string, any>): void;
+    /**
+     * Track agent execution
+     */
+    trackAgentExecution(agentName: string, duration: number, success: boolean): void;
+    /**
+     * Track tool call
+     */
+    trackToolCall(toolName: string, duration: number, success: boolean): void;
+    /**
+     * Track LLM call
+     */
+    trackLLMCall(provider: string, model: string, tokens: number, duration: number): void;
+    /**
+     * Track error
+     */
+    trackError(error: string, context?: Record<string, any>): void;
+    /**
+     * Set user ID
+     */
+    setUserId(userId: string): void;
+    /**
+     * Flush events
+     */
+    flush(): Promise<void>;
+    /**
+     * Enable telemetry
+     */
+    enable(): void;
+    /**
+     * Disable telemetry
+     */
+    disable(): void;
+    /**
+     * Check if telemetry is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get pending events count
+     */
+    getPendingCount(): number;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): void;
+    private startFlushTimer;
+    private stopFlushTimer;
+    private generateSessionId;
+}
+/**
+ * Get global telemetry instance
+ */
+export declare function getTelemetry(): TelemetryCollector;
+/**
+ * Enable telemetry
+ */
+export declare function enableTelemetry(): void;
+/**
+ * Disable telemetry
+ */
+export declare function disableTelemetry(): void;
+/**
+ * Cleanup telemetry resources
+ */
+export declare function cleanupTelemetry(): void;
+/**
+ * AgentTelemetry - Agent-focused telemetry wrapper
+ *
+ * @example Simple usage (3 lines)
+ * ```typescript
+ * import { Agent } from 'praisonai';
+ *
+ * // Enable telemetry on agent
+ * const agent = new Agent({
+ *   instructions: 'You are helpful',
+ *   telemetry: true  // Opt-in telemetry
+ * });
+ * await agent.chat('Hello!');  // Automatically tracked
+ * ```
+ *
+ * @example Manual tracking
+ * ```typescript
+ * import { AgentTelemetry } from 'praisonai';
+ *
+ * const telemetry = new AgentTelemetry('MyAgent');
+ * const result = await telemetry.trackChat(async () => {
+ *   return await agent.chat('Hello!');
+ * });
+ * console.log(telemetry.getStats());
+ * ```
+ */
+export interface AgentStats {
+    totalChats: number;
+    successfulChats: number;
+    failedChats: number;
+    totalDuration: number;
+    avgDuration: number;
+    totalTokens: number;
+    toolCalls: number;
+}
+export declare class AgentTelemetry {
+    private agentName;
+    private collector;
+    private stats;
+    constructor(agentName: string, config?: TelemetryConfig);
+    /**
+     * Track a chat execution
+     */
+    trackChat<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Track a tool call
+     */
+    trackToolCall(toolName: string, duration: number, success: boolean): void;
+    /**
+     * Track token usage
+     */
+    trackTokens(tokens: number): void;
+    /**
+     * Get agent statistics
+     */
+    getStats(): AgentStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Get success rate
+     */
+    getSuccessRate(): number;
+    /**
+     * Print summary
+     */
+    printSummary(): void;
+}
+/**
+ * Create agent telemetry
+ */
+export declare function createAgentTelemetry(agentName: string, config?: TelemetryConfig): AgentTelemetry;

package/dist/telemetry/index.js

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * Telemetry - Usage tracking and analytics
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentTelemetry = exports.TelemetryCollector = void 0;
+exports.getTelemetry = getTelemetry;
+exports.enableTelemetry = enableTelemetry;
+exports.disableTelemetry = disableTelemetry;
+exports.cleanupTelemetry = cleanupTelemetry;
+exports.createAgentTelemetry = createAgentTelemetry;
+/**
+ * Telemetry collector for tracking usage
+ */
+class TelemetryCollector {
+    constructor(config = {}) {
+        this.events = [];
+        this.enabled = config.enabled ?? this.checkEnabled();
+        this.endpoint = config.endpoint;
+        this.batchSize = config.batchSize ?? 100;
+        this.flushInterval = config.flushInterval ?? 60000;
+        this.sessionId = this.generateSessionId();
+        if (this.enabled && this.flushInterval > 0) {
+            this.startFlushTimer();
+        }
+    }
+    checkEnabled() {
+        const disabled = process.env.PRAISONAI_TELEMETRY_DISABLED === 'true' ||
+            process.env.PRAISONAI_DISABLE_TELEMETRY === 'true' ||
+            process.env.DO_NOT_TRACK === 'true';
+        return !disabled;
+    }
+    /**
+     * Track an event
+     */
+    track(name, properties) {
+        if (!this.enabled)
+            return;
+        const event = {
+            name,
+            timestamp: Date.now(),
+            properties,
+            userId: this.userId,
+            sessionId: this.sessionId
+        };
+        this.events.push(event);
+        if (this.events.length >= this.batchSize) {
+            this.flush();
+        }
+    }
+    /**
+     * Track feature usage
+     */
+    trackFeatureUsage(feature, metadata) {
+        this.track('feature_usage', { feature, ...metadata });
+    }
+    /**
+     * Track agent execution
+     */
+    trackAgentExecution(agentName, duration, success) {
+        this.track('agent_execution', { agentName, duration, success });
+    }
+    /**
+     * Track tool call
+     */
+    trackToolCall(toolName, duration, success) {
+        this.track('tool_call', { toolName, duration, success });
+    }
+    /**
+     * Track LLM call
+     */
+    trackLLMCall(provider, model, tokens, duration) {
+        this.track('llm_call', { provider, model, tokens, duration });
+    }
+    /**
+     * Track error
+     */
+    trackError(error, context) {
+        this.track('error', { error, ...context });
+    }
+    /**
+     * Set user ID
+     */
+    setUserId(userId) {
+        this.userId = userId;
+    }
+    /**
+     * Flush events
+     */
+    async flush() {
+        if (this.events.length === 0)
+            return;
+        const eventsToSend = [...this.events];
+        this.events = [];
+        if (this.endpoint) {
+            try {
+                await fetch(this.endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ events: eventsToSend })
+                });
+            }
+            catch (error) {
+                // Silently fail - never break user applications
+            }
+        }
+    }
+    /**
+     * Enable telemetry
+     */
+    enable() {
+        this.enabled = true;
+        this.startFlushTimer();
+    }
+    /**
+     * Disable telemetry
+     */
+    disable() {
+        this.enabled = false;
+        this.stopFlushTimer();
+        this.events = [];
+    }
+    /**
+     * Check if telemetry is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get pending events count
+     */
+    getPendingCount() {
+        return this.events.length;
+    }
+    /**
+     * Cleanup resources
+     */
+    cleanup() {
+        this.stopFlushTimer();
+        this.flush();
+    }
+    startFlushTimer() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setInterval(() => this.flush(), this.flushInterval);
+    }
+    stopFlushTimer() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+    }
+    generateSessionId() {
+        return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+}
+exports.TelemetryCollector = TelemetryCollector;
+// Global telemetry instance
+let globalTelemetry = null;
+/**
+ * Get global telemetry instance
+ */
+function getTelemetry() {
+    if (!globalTelemetry) {
+        globalTelemetry = new TelemetryCollector();
+    }
+    return globalTelemetry;
+}
+/**
+ * Enable telemetry
+ */
+function enableTelemetry() {
+    getTelemetry().enable();
+}
+/**
+ * Disable telemetry
+ */
+function disableTelemetry() {
+    getTelemetry().disable();
+}
+/**
+ * Cleanup telemetry resources
+ */
+function cleanupTelemetry() {
+    if (globalTelemetry) {
+        globalTelemetry.cleanup();
+    }
+}
+class AgentTelemetry {
+    constructor(agentName, config) {
+        this.stats = {
+            totalChats: 0,
+            successfulChats: 0,
+            failedChats: 0,
+            totalDuration: 0,
+            avgDuration: 0,
+            totalTokens: 0,
+            toolCalls: 0
+        };
+        this.agentName = agentName;
+        this.collector = config ? new TelemetryCollector(config) : getTelemetry();
+    }
+    /**
+     * Track a chat execution
+     */
+    async trackChat(fn) {
+        const startTime = Date.now();
+        this.stats.totalChats++;
+        try {
+            const result = await fn();
+            const duration = Date.now() - startTime;
+            this.stats.successfulChats++;
+            this.stats.totalDuration += duration;
+            this.stats.avgDuration = this.stats.totalDuration / this.stats.totalChats;
+            this.collector.trackAgentExecution(this.agentName, duration, true);
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            this.stats.failedChats++;
+            this.stats.totalDuration += duration;
+            this.stats.avgDuration = this.stats.totalDuration / this.stats.totalChats;
+            this.collector.trackAgentExecution(this.agentName, duration, false);
+            this.collector.trackError(String(error), { agent: this.agentName });
+            throw error;
+        }
+    }
+    /**
+     * Track a tool call
+     */
+    trackToolCall(toolName, duration, success) {
+        this.stats.toolCalls++;
+        this.collector.trackToolCall(toolName, duration, success);
+    }
+    /**
+     * Track token usage
+     */
+    trackTokens(tokens) {
+        this.stats.totalTokens += tokens;
+    }
+    /**
+     * Get agent statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.stats = {
+            totalChats: 0,
+            successfulChats: 0,
+            failedChats: 0,
+            totalDuration: 0,
+            avgDuration: 0,
+            totalTokens: 0,
+            toolCalls: 0
+        };
+    }
+    /**
+     * Get success rate
+     */
+    getSuccessRate() {
+        if (this.stats.totalChats === 0)
+            return 0;
+        return (this.stats.successfulChats / this.stats.totalChats) * 100;
+    }
+    /**
+     * Print summary
+     */
+    printSummary() {
+        console.log(`\n📊 Agent Telemetry: ${this.agentName}`);
+        console.log(`   Total chats: ${this.stats.totalChats}`);
+        console.log(`   Success rate: ${this.getSuccessRate().toFixed(1)}%`);
+        console.log(`   Avg duration: ${this.stats.avgDuration.toFixed(0)}ms`);
+        console.log(`   Tool calls: ${this.stats.toolCalls}`);
+        console.log(`   Total tokens: ${this.stats.totalTokens}`);
+    }
+}
+exports.AgentTelemetry = AgentTelemetry;
+/**
+ * Create agent telemetry
+ */
+function createAgentTelemetry(agentName, config) {
+    return new AgentTelemetry(agentName, config);
+}

package/dist/tools/arxivTools.d.ts

@@ -0,0 +1,32 @@
+import { BaseTool } from './base';
+export interface ArxivPaper {
+    id: string;
+    title: string;
+    authors: string[];
+    summary: string;
+    published: string;
+    updated: string;
+    link: string;
+}
+export declare class ArxivSearchTool extends BaseTool<{
+    query: string;
+    maxResults?: number;
+}, ArxivPaper[]> {
+    name: string;
+    description: string;
+    private parser;
+    constructor();
+    run(params: {
+        query: string;
+        maxResults?: number;
+    }): Promise<ArxivPaper[]>;
+}
+export declare class ArxivDownloadTool extends BaseTool<{
+    paperId: string;
+}, Buffer> {
+    name: string;
+    description: string;
+    run(params: {
+        paperId: string;
+    }): Promise<Buffer>;
+}

package/dist/tools/arxivTools.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArxivDownloadTool = exports.ArxivSearchTool = void 0;
+const axios_1 = __importDefault(require("axios"));
+const fast_xml_parser_1 = require("fast-xml-parser");
+const base_1 = require("./base");
+class ArxivSearchTool extends base_1.BaseTool {
+    constructor() {
+        super();
+        this.name = 'arxiv-search';
+        this.description = 'Search for academic papers on arXiv';
+        this.parser = new fast_xml_parser_1.XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: '@_'
+        });
+    }
+    async run(params) {
+        const { query, maxResults = 10 } = params;
+        try {
+            const response = await axios_1.default.get(`http://export.arxiv.org/api/query`, {
+                params: {
+                    search_query: encodeURIComponent(query),
+                    max_results: maxResults,
+                    sortBy: 'lastUpdatedDate',
+                    sortOrder: 'descending'
+                }
+            });
+            const parsed = this.parser.parse(response.data);
+            const entries = parsed.feed.entry;
+            if (!entries) {
+                return [];
+            }
+            // Handle both single and multiple entries
+            const entriesArray = Array.isArray(entries) ? entries : [entries];
+            return entriesArray.map((entry) => ({
+                id: entry.id.split('/abs/')[1],
+                title: entry.title.replace(/\s+/g, ' ').trim(),
+                authors: Array.isArray(entry.author)
+                    ? entry.author.map((a) => a.name)
+                    : [entry.author.name],
+                summary: entry.summary.replace(/\s+/g, ' ').trim(),
+                published: entry.published,
+                updated: entry.updated,
+                link: entry.id
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to search arXiv: ${error.message}`);
+            }
+            throw new Error('Failed to search arXiv: Unknown error');
+        }
+    }
+}
+exports.ArxivSearchTool = ArxivSearchTool;
+class ArxivDownloadTool extends base_1.BaseTool {
+    constructor() {
+        super(...arguments);
+        this.name = 'arxiv-download';
+        this.description = 'Download PDF of an arXiv paper';
+    }
+    async run(params) {
+        const { paperId } = params;
+        try {
+            const response = await axios_1.default.get(`https://arxiv.org/pdf/${paperId}.pdf`, {
+                responseType: 'arraybuffer'
+            });
+            return Buffer.from(response.data);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to download paper: ${error.message}`);
+            }
+            throw new Error('Failed to download paper: Unknown error');
+        }
+    }
+}
+exports.ArxivDownloadTool = ArxivDownloadTool;

package/dist/tools/base.d.ts

@@ -0,0 +1,97 @@
+/**
+ * BaseTool - Abstract base class for creating custom tools (plugins)
+ *
+ * This provides the same extensibility pattern as Python's BaseTool.
+ * External developers can create plugins by extending BaseTool.
+ *
+ * Usage:
+ *   import { BaseTool } from 'praisonai';
+ *
+ *   class MyTool extends BaseTool {
+ *     name = 'my_tool';
+ *     description = 'Does something useful';
+ *
+ *     async run(params: { query: string }): Promise<string> {
+ *       return `Result for ${params.query}`;
+ *     }
+ *   }
+ */
+export interface ToolResult<T = any> {
+    output: T;
+    success: boolean;
+    error?: string;
+    metadata?: Record<string, any>;
+}
+export declare class ToolValidationError extends Error {
+    constructor(message: string);
+}
+export interface ToolParameters {
+    type: 'object';
+    properties: Record<string, {
+        type: string;
+        description?: string;
+        enum?: string[];
+        default?: any;
+    }>;
+    required?: string[];
+}
+/**
+ * Abstract base class for all PraisonAI tools.
+ *
+ * Subclass this to create custom tools that can be:
+ * - Used directly by agents
+ * - Distributed as npm packages (plugins)
+ * - Auto-discovered via package.json
+ */
+export declare abstract class BaseTool<TParams = any, TResult = any> {
+    /** Unique identifier for the tool */
+    abstract name: string;
+    /** Human-readable description (used by LLM) */
+    abstract description: string;
+    /** Tool version string */
+    version: string;
+    /** JSON Schema for parameters */
+    parameters?: ToolParameters;
+    /**
+     * Execute the tool with given arguments.
+     * This method must be implemented by subclasses.
+     */
+    abstract run(params: TParams): Promise<TResult> | TResult;
+    /**
+     * Allow tool to be called directly like a function.
+     */
+    execute(params: TParams): Promise<TResult>;
+    /**
+     * Execute tool with error handling, returning ToolResult.
+     */
+    safeRun(params: TParams): Promise<ToolResult<TResult>>;
+    /**
+     * Get OpenAI-compatible function schema for this tool.
+     */
+    getSchema(): {
+        type: 'function';
+        function: {
+            name: string;
+            description: string;
+            parameters: any;
+        };
+    };
+    /**
+     * Validate the tool configuration.
+     */
+    validate(): boolean;
+    toString(): string;
+}
+/**
+ * Validate any tool-like object.
+ */
+export declare function validateTool(tool: any): boolean;
+/**
+ * Create a simple tool from a function (alternative to class-based approach)
+ */
+export declare function createTool<TParams = any, TResult = any>(config: {
+    name: string;
+    description: string;
+    parameters?: ToolParameters;
+    run: (params: TParams) => Promise<TResult> | TResult;
+}): BaseTool<TParams, TResult>;