praisonai 1.2.0 → 1.2.2

package/dist/knowledge/reranker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Reranker - Rerank search results for improved relevance
+ * Inspired by mastra's rerank module
+ */
+export interface RerankResult {
+    id: string;
+    score: number;
+    content: string;
+    metadata?: Record<string, any>;
+    originalRank: number;
+    newRank: number;
+}
+export interface RerankConfig {
+    model?: string;
+    topK?: number;
+    threshold?: number;
+}
+/**
+ * Abstract base class for rerankers
+ */
+export declare abstract class BaseReranker {
+    readonly name: string;
+    constructor(name: string);
+    abstract rerank(query: string, documents: Array<{
+        id: string;
+        content: string;
+        metadata?: Record<string, any>;
+    }>, config?: RerankConfig): Promise<RerankResult[]>;
+}
+/**
+ * Cohere Reranker - Uses Cohere's rerank API
+ */
+export declare class CohereReranker extends BaseReranker {
+    private apiKey;
+    private model;
+    constructor(config?: {
+        apiKey?: string;
+        model?: string;
+    });
+    rerank(query: string, documents: Array<{
+        id: string;
+        content: string;
+        metadata?: Record<string, any>;
+    }>, config?: RerankConfig): Promise<RerankResult[]>;
+}
+/**
+ * Cross-Encoder Reranker - Uses sentence similarity for reranking
+ * This is a simple implementation using cosine similarity
+ */
+export declare class CrossEncoderReranker extends BaseReranker {
+    private embedFn?;
+    constructor(config?: {
+        embedFn?: (texts: string[]) => Promise<number[][]>;
+    });
+    rerank(query: string, documents: Array<{
+        id: string;
+        content: string;
+        metadata?: Record<string, any>;
+    }>, config?: RerankConfig): Promise<RerankResult[]>;
+    private keywordRerank;
+    private cosineSimilarity;
+}
+/**
+ * LLM Reranker - Uses an LLM to score relevance
+ */
+export declare class LLMReranker extends BaseReranker {
+    private generateFn;
+    constructor(config: {
+        generateFn: (prompt: string) => Promise<string>;
+    });
+    rerank(query: string, documents: Array<{
+        id: string;
+        content: string;
+        metadata?: Record<string, any>;
+    }>, config?: RerankConfig): Promise<RerankResult[]>;
+}
+export declare function createCohereReranker(config?: {
+    apiKey?: string;
+    model?: string;
+}): CohereReranker;
+export declare function createCrossEncoderReranker(config?: {
+    embedFn?: (texts: string[]) => Promise<number[][]>;
+}): CrossEncoderReranker;
+export declare function createLLMReranker(config: {
+    generateFn: (prompt: string) => Promise<string>;
+}): LLMReranker;

package/dist/knowledge/reranker.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * Reranker - Rerank search results for improved relevance
+ * Inspired by mastra's rerank module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMReranker = exports.CrossEncoderReranker = exports.CohereReranker = exports.BaseReranker = void 0;
+exports.createCohereReranker = createCohereReranker;
+exports.createCrossEncoderReranker = createCrossEncoderReranker;
+exports.createLLMReranker = createLLMReranker;
+/**
+ * Abstract base class for rerankers
+ */
+class BaseReranker {
+    constructor(name) {
+        this.name = name;
+    }
+}
+exports.BaseReranker = BaseReranker;
+/**
+ * Cohere Reranker - Uses Cohere's rerank API
+ */
+class CohereReranker extends BaseReranker {
+    constructor(config = {}) {
+        super('CohereReranker');
+        this.apiKey = config.apiKey || process.env.COHERE_API_KEY || '';
+        this.model = config.model || 'rerank-english-v3.0';
+    }
+    async rerank(query, documents, config) {
+        if (!this.apiKey) {
+            throw new Error('Cohere API key required for reranking');
+        }
+        const response = await fetch('https://api.cohere.ai/v1/rerank', {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                model: config?.model || this.model,
+                query,
+                documents: documents.map(d => d.content),
+                top_n: config?.topK || documents.length,
+                return_documents: true
+            })
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Cohere rerank error: ${response.status} - ${error}`);
+        }
+        const data = await response.json();
+        const threshold = config?.threshold || 0;
+        return (data.results || [])
+            .filter((r) => r.relevance_score >= threshold)
+            .map((r, newRank) => ({
+            id: documents[r.index].id,
+            score: r.relevance_score,
+            content: documents[r.index].content,
+            metadata: documents[r.index].metadata,
+            originalRank: r.index,
+            newRank
+        }));
+    }
+}
+exports.CohereReranker = CohereReranker;
+/**
+ * Cross-Encoder Reranker - Uses sentence similarity for reranking
+ * This is a simple implementation using cosine similarity
+ */
+class CrossEncoderReranker extends BaseReranker {
+    constructor(config = {}) {
+        super('CrossEncoderReranker');
+        this.embedFn = config.embedFn;
+    }
+    async rerank(query, documents, config) {
+        if (!this.embedFn) {
+            // Fallback to simple keyword matching
+            return this.keywordRerank(query, documents, config);
+        }
+        // Get embeddings for query and all documents
+        const texts = [query, ...documents.map(d => d.content)];
+        const embeddings = await this.embedFn(texts);
+        const queryEmbedding = embeddings[0];
+        const docEmbeddings = embeddings.slice(1);
+        // Calculate similarity scores
+        const scores = docEmbeddings.map((docEmb, i) => ({
+            index: i,
+            score: this.cosineSimilarity(queryEmbedding, docEmb)
+        }));
+        // Sort by score descending
+        scores.sort((a, b) => b.score - a.score);
+        const threshold = config?.threshold || 0;
+        const topK = config?.topK || documents.length;
+        return scores
+            .filter(s => s.score >= threshold)
+            .slice(0, topK)
+            .map((s, newRank) => ({
+            id: documents[s.index].id,
+            score: s.score,
+            content: documents[s.index].content,
+            metadata: documents[s.index].metadata,
+            originalRank: s.index,
+            newRank
+        }));
+    }
+    keywordRerank(query, documents, config) {
+        const queryTerms = query.toLowerCase().split(/\s+/);
+        const scores = documents.map((doc, i) => {
+            const content = doc.content.toLowerCase();
+            let score = 0;
+            for (const term of queryTerms) {
+                if (content.includes(term)) {
+                    score += 1;
+                }
+            }
+            // Normalize by query length
+            score = score / queryTerms.length;
+            return { index: i, score };
+        });
+        scores.sort((a, b) => b.score - a.score);
+        const threshold = config?.threshold || 0;
+        const topK = config?.topK || documents.length;
+        return scores
+            .filter(s => s.score >= threshold)
+            .slice(0, topK)
+            .map((s, newRank) => ({
+            id: documents[s.index].id,
+            score: s.score,
+            content: documents[s.index].content,
+            metadata: documents[s.index].metadata,
+            originalRank: s.index,
+            newRank
+        }));
+    }
+    cosineSimilarity(a, b) {
+        const dot = a.reduce((sum, x, i) => sum + x * b[i], 0);
+        const normA = Math.sqrt(a.reduce((sum, x) => sum + x * x, 0));
+        const normB = Math.sqrt(b.reduce((sum, x) => sum + x * x, 0));
+        return dot / (normA * normB);
+    }
+}
+exports.CrossEncoderReranker = CrossEncoderReranker;
+/**
+ * LLM Reranker - Uses an LLM to score relevance
+ */
+class LLMReranker extends BaseReranker {
+    constructor(config) {
+        super('LLMReranker');
+        this.generateFn = config.generateFn;
+    }
+    async rerank(query, documents, config) {
+        const scores = [];
+        // Score each document
+        for (let i = 0; i < documents.length; i++) {
+            const doc = documents[i];
+            const prompt = `Rate the relevance of the following document to the query on a scale of 0 to 10.
+Query: ${query}
+Document: ${doc.content.slice(0, 500)}
+
+Respond with only a number between 0 and 10.`;
+            try {
+                const response = await this.generateFn(prompt);
+                const score = parseFloat(response.trim()) / 10;
+                scores.push({ index: i, score: isNaN(score) ? 0 : Math.min(1, Math.max(0, score)) });
+            }
+            catch {
+                scores.push({ index: i, score: 0 });
+            }
+        }
+        scores.sort((a, b) => b.score - a.score);
+        const threshold = config?.threshold || 0;
+        const topK = config?.topK || documents.length;
+        return scores
+            .filter(s => s.score >= threshold)
+            .slice(0, topK)
+            .map((s, newRank) => ({
+            id: documents[s.index].id,
+            score: s.score,
+            content: documents[s.index].content,
+            metadata: documents[s.index].metadata,
+            originalRank: s.index,
+            newRank
+        }));
+    }
+}
+exports.LLMReranker = LLMReranker;
+// Factory functions
+function createCohereReranker(config) {
+    return new CohereReranker(config);
+}
+function createCrossEncoderReranker(config) {
+    return new CrossEncoderReranker(config);
+}
+function createLLMReranker(config) {
+    return new LLMReranker(config);
+}

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: {