praisonai 1.2.0 → 1.2.1

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export * from './knowledge';
 export * from './llm';
 export * from './memory';
 export * from './process';
-export { Tool, BaseTool, FunctionTool, tool, ToolRegistry, getRegistry, registerTool, getTool, type ToolConfig, type ToolContext, type ToolParameters } from './tools';
+export { BaseTool, ToolResult, ToolValidationError, validateTool, createTool, FunctionTool, tool, ToolRegistry, getRegistry, registerTool, getTool, type ToolConfig, type ToolContext, type ToolParameters } from './tools';
 export * from './tools/arxivTools';
 export * from './tools/mcpSse';
 export * from './session';

package/dist/index.js

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Chunking = exports.createPromptExpanderAgent = exports.PromptExpanderAgent = exports.createQueryRewriterAgent = exports.QueryRewriterAgent = exports.createDeepResearchAgent = exports.DeepResearchAgent = exports.createImageAgent = exports.ImageAgent = exports.createAutoAgents = exports.AutoAgents = exports.cleanupTelemetry = exports.disableTelemetry = exports.enableTelemetry = exports.getTelemetry = exports.TelemetryCollector = exports.createMemory = exports.Memory = exports.help = exports.version = exports.listProviders = exports.chat = exports.parseSkillFile = exports.createSkillManager = exports.SkillManager = exports.getObservabilityAdapter = exports.setObservabilityAdapter = exports.ConsoleObservabilityAdapter = exports.MemoryObservabilityAdapter = exports.EvalSuite = exports.reliabilityEval = exports.performanceEval = exports.accuracyEval = exports.createKnowledgeBase = exports.KnowledgeBase = exports.createContextAgent = exports.ContextAgent = exports.routeConditions = exports.createRouter = exports.RouterAgent = exports.handoffFilters = exports.handoff = exports.Handoff = exports.getTool = exports.registerTool = exports.getRegistry = exports.ToolRegistry = exports.tool = exports.FunctionTool = exports.BaseTool = void 0;
-exports.BaseProvider = exports.GoogleProvider = exports.AnthropicProvider = exports.OpenAIProvider = exports.getAvailableProviders = exports.isProviderAvailable = exports.parseModelString = exports.getDefaultProvider = exports.createProvider = exports.createPlanStorage = exports.createTodoList = exports.createPlan = exports.PlanStorage = exports.TodoItem = exports.TodoList = exports.PlanStep = exports.Plan = exports.createLLMGuardrail = exports.LLMGuardrail = exports.createChunking = void 0;
+exports.createQueryRewriterAgent = exports.QueryRewriterAgent = exports.createDeepResearchAgent = exports.DeepResearchAgent = exports.createImageAgent = exports.ImageAgent = exports.createAutoAgents = exports.AutoAgents = exports.cleanupTelemetry = exports.disableTelemetry = exports.enableTelemetry = exports.getTelemetry = exports.TelemetryCollector = exports.createMemory = exports.Memory = exports.help = exports.version = exports.listProviders = exports.chat = exports.parseSkillFile = exports.createSkillManager = exports.SkillManager = exports.getObservabilityAdapter = exports.setObservabilityAdapter = exports.ConsoleObservabilityAdapter = exports.MemoryObservabilityAdapter = exports.EvalSuite = exports.reliabilityEval = exports.performanceEval = exports.accuracyEval = exports.createKnowledgeBase = exports.KnowledgeBase = exports.createContextAgent = exports.ContextAgent = exports.routeConditions = exports.createRouter = exports.RouterAgent = exports.handoffFilters = exports.handoff = exports.Handoff = exports.getTool = exports.registerTool = exports.getRegistry = exports.ToolRegistry = exports.tool = exports.FunctionTool = exports.createTool = exports.validateTool = exports.ToolValidationError = exports.BaseTool = void 0;
+exports.BaseProvider = exports.GoogleProvider = exports.AnthropicProvider = exports.OpenAIProvider = exports.getAvailableProviders = exports.isProviderAvailable = exports.parseModelString = exports.getDefaultProvider = exports.createProvider = exports.createPlanStorage = exports.createTodoList = exports.createPlan = exports.PlanStorage = exports.TodoItem = exports.TodoList = exports.PlanStep = exports.Plan = exports.createLLMGuardrail = exports.LLMGuardrail = exports.createChunking = exports.Chunking = exports.createPromptExpanderAgent = exports.PromptExpanderAgent = void 0;
 // Export all public modules
 __exportStar(require("./agent"), exports);
 __exportStar(require("./knowledge"), exports);
@@ -25,6 +25,9 @@ __exportStar(require("./process"), exports);
 // Export tools (excluding conflicting types)
 var tools_1 = require("./tools");
 Object.defineProperty(exports, "BaseTool", { enumerable: true, get: function () { return tools_1.BaseTool; } });
+Object.defineProperty(exports, "ToolValidationError", { enumerable: true, get: function () { return tools_1.ToolValidationError; } });
+Object.defineProperty(exports, "validateTool", { enumerable: true, get: function () { return tools_1.validateTool; } });
+Object.defineProperty(exports, "createTool", { enumerable: true, get: function () { return tools_1.createTool; } });
 Object.defineProperty(exports, "FunctionTool", { enumerable: true, get: function () { return tools_1.FunctionTool; } });
 Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return tools_1.tool; } });
 Object.defineProperty(exports, "ToolRegistry", { enumerable: true, get: function () { return tools_1.ToolRegistry; } });

package/dist/tools/arxivTools.d.ts

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

package/dist/tools/arxivTools.js

@@ -5,17 +5,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArxivDownloadTool = exports.ArxivSearchTool = void 0;
 const axios_1 = __importDefault(require("axios"));
-const index_1 = require("./index");
 const fast_xml_parser_1 = require("fast-xml-parser");
-class ArxivSearchTool extends index_1.BaseTool {
+const base_1 = require("./base");
+class ArxivSearchTool extends base_1.BaseTool {
     constructor() {
-        super('arxiv-search', 'Search for academic papers on arXiv');
+        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 execute(query, maxResults = 10) {
+    async run(params) {
+        const { query, maxResults = 10 } = params;
         try {
             const response = await axios_1.default.get(`http://export.arxiv.org/api/query`, {
                 params: {
@@ -53,11 +56,14 @@ class ArxivSearchTool extends index_1.BaseTool {
     }
 }
 exports.ArxivSearchTool = ArxivSearchTool;
-class ArxivDownloadTool extends index_1.BaseTool {
+class ArxivDownloadTool extends base_1.BaseTool {
     constructor() {
-        super('arxiv-download', 'Download PDF of an arXiv paper');
+        super(...arguments);
+        this.name = 'arxiv-download';
+        this.description = 'Download PDF of an arXiv paper';
     }
-    async execute(paperId) {
+    async run(params) {
+        const { paperId } = params;
         try {
             const response = await axios_1.default.get(`https://arxiv.org/pdf/${paperId}.pdf`, {
                 responseType: 'arraybuffer'

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>;

package/dist/tools/base.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * 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}`;
+ *     }
+ *   }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseTool = exports.ToolValidationError = void 0;
+exports.validateTool = validateTool;
+exports.createTool = createTool;
+class ToolValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolValidationError';
+    }
+}
+exports.ToolValidationError = ToolValidationError;
+/**
+ * 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
+ */
+class BaseTool {
+    constructor() {
+        /** Tool version string */
+        this.version = '1.0.0';
+    }
+    /**
+     * Allow tool to be called directly like a function.
+     */
+    async execute(params) {
+        return this.run(params);
+    }
+    /**
+     * Execute tool with error handling, returning ToolResult.
+     */
+    async safeRun(params) {
+        try {
+            const output = await this.run(params);
+            return { output, success: true };
+        }
+        catch (error) {
+            return {
+                output: null,
+                success: false,
+                error: error.message
+            };
+        }
+    }
+    /**
+     * Get OpenAI-compatible function schema for this tool.
+     */
+    getSchema() {
+        return {
+            type: 'function',
+            function: {
+                name: this.name,
+                description: this.description,
+                parameters: this.parameters || { type: 'object', properties: {}, required: [] }
+            }
+        };
+    }
+    /**
+     * Validate the tool configuration.
+     */
+    validate() {
+        const errors = [];
+        if (!this.name || typeof this.name !== 'string') {
+            errors.push("Tool must have a non-empty string 'name'");
+        }
+        if (!this.description || typeof this.description !== 'string') {
+            errors.push("Tool must have a non-empty string 'description'");
+        }
+        if (errors.length > 0) {
+            throw new ToolValidationError(`Tool '${this.name}' validation failed: ${errors.join('; ')}`);
+        }
+        return true;
+    }
+    toString() {
+        return `${this.constructor.name}(name='${this.name}')`;
+    }
+}
+exports.BaseTool = BaseTool;
+/**
+ * Validate any tool-like object.
+ */
+function validateTool(tool) {
+    if (tool instanceof BaseTool) {
+        return tool.validate();
+    }
+    if (typeof tool === 'function' || (tool && typeof tool.run === 'function')) {
+        const name = tool.name || tool.__name__;
+        if (!name) {
+            throw new ToolValidationError('Tool must have a name');
+        }
+        return true;
+    }
+    throw new ToolValidationError(`Invalid tool type: ${typeof tool}`);
+}
+/**
+ * Create a simple tool from a function (alternative to class-based approach)
+ */
+function createTool(config) {
+    return {
+        name: config.name,
+        description: config.description,
+        version: '1.0.0',
+        parameters: config.parameters,
+        run: config.run,
+        execute: async (params) => config.run(params),
+        safeRun: async (params) => {
+            try {
+                const output = await config.run(params);
+                return { output, success: true };
+            }
+            catch (error) {
+                return { output: null, success: false, error: error.message };
+            }
+        },
+        getSchema: () => ({
+            type: 'function',
+            function: {
+                name: config.name,
+                description: config.description,
+                parameters: config.parameters || { type: 'object', properties: {}, required: [] }
+            }
+        }),
+        validate: () => true,
+        toString: () => `Tool(name='${config.name}')`
+    };
+}

package/dist/tools/index.d.ts

@@ -1,14 +1,4 @@
-export interface Tool {
-    name: string;
-    description: string;
-    execute(...args: any[]): Promise<any>;
-}
-export declare class BaseTool implements Tool {
-    name: string;
-    description: string;
-    constructor(name: string, description: string);
-    execute(...args: any[]): Promise<any>;
-}
+export { BaseTool, ToolResult, ToolValidationError, validateTool, createTool, type ToolParameters } from './base';
 export * from './decorator';
 export * from './arxivTools';
 export * from './mcpSse';

package/dist/tools/index.js

@@ -14,17 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseTool = void 0;
-class BaseTool {
-    constructor(name, description) {
-        this.name = name;
-        this.description = description;
-    }
-    async execute(...args) {
-        throw new Error('Method not implemented.');
-    }
-}
-exports.BaseTool = BaseTool;
+exports.createTool = exports.validateTool = exports.ToolValidationError = exports.BaseTool = void 0;
+// Export base tool interfaces and classes
+var base_1 = require("./base");
+Object.defineProperty(exports, "BaseTool", { enumerable: true, get: function () { return base_1.BaseTool; } });
+Object.defineProperty(exports, "ToolValidationError", { enumerable: true, get: function () { return base_1.ToolValidationError; } });
+Object.defineProperty(exports, "validateTool", { enumerable: true, get: function () { return base_1.validateTool; } });
+Object.defineProperty(exports, "createTool", { enumerable: true, get: function () { return base_1.createTool; } });
 // Export decorator and registry
 __exportStar(require("./decorator"), exports);
 // Export all tool modules

package/dist/tools/mcpSse.d.ts

@@ -1,16 +1,18 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { BaseTool } from './index';
+import { BaseTool } from './base';
 export interface MCPToolInfo {
     name: string;
     description?: string;
     inputSchema?: any;
 }
-export declare class MCPTool extends BaseTool {
+export declare class MCPTool extends BaseTool<any, any> {
+    name: string;
+    description: string;
     private client;
     private inputSchema;
     constructor(info: MCPToolInfo, client: Client);
     get schemaProperties(): Record<string, any> | undefined;
-    execute(args?: any): Promise<any>;
+    run(args?: any): Promise<any>;
     toOpenAITool(): {
         type: string;
         function: {

package/dist/tools/mcpSse.js

@@ -3,17 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MCP = exports.MCPTool = void 0;
 const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
 const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
-const index_1 = require("./index");
-class MCPTool extends index_1.BaseTool {
+const base_1 = require("./base");
+class MCPTool extends base_1.BaseTool {
     constructor(info, client) {
-        super(info.name, info.description || `Call the ${info.name} tool`);
+        super();
+        this.name = info.name;
+        this.description = info.description || `Call the ${info.name} tool`;
         this.client = client;
         this.inputSchema = info.inputSchema || { type: 'object', properties: {}, required: [] };
     }
     get schemaProperties() {
         return this.inputSchema?.properties;
     }
-    async execute(args = {}) {
+    async run(args = {}) {
         try {
             const result = await this.client.callTool({ name: this.name, arguments: args });
             if (result.structuredContent) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praisonai",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "PraisonAI TypeScript AI Agents Framework - Node.js, npm, and Javascript AI Agents Framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",