praisonai 1.2.1 → 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/workflows/yaml-parser.d.ts

@@ -0,0 +1,48 @@
+/**
+ * YAML Workflow Parser
+ * Parse YAML workflow definitions into executable workflows
+ */
+import { Workflow } from './index';
+export interface YAMLWorkflowDefinition {
+    name: string;
+    description?: string;
+    version?: string;
+    steps: YAMLStepDefinition[];
+    metadata?: Record<string, any>;
+}
+export interface YAMLStepDefinition {
+    name: string;
+    type: 'agent' | 'tool' | 'condition' | 'parallel' | 'loop';
+    agent?: string;
+    tool?: string;
+    input?: string | Record<string, any>;
+    output?: string;
+    condition?: string;
+    onError?: 'fail' | 'skip' | 'retry';
+    maxRetries?: number;
+    timeout?: number;
+    steps?: YAMLStepDefinition[];
+    loopCondition?: string;
+    maxIterations?: number;
+}
+export interface ParsedWorkflow {
+    workflow: Workflow;
+    definition: YAMLWorkflowDefinition;
+    errors: string[];
+}
+/**
+ * Parse YAML string into workflow definition
+ */
+export declare function parseYAMLWorkflow(yamlContent: string): YAMLWorkflowDefinition;
+/**
+ * Create executable workflow from YAML definition
+ */
+export declare function createWorkflowFromYAML(definition: YAMLWorkflowDefinition, agents?: Record<string, any>, tools?: Record<string, any>): ParsedWorkflow;
+/**
+ * Load workflow from YAML file
+ */
+export declare function loadWorkflowFromFile(filePath: string, agents?: Record<string, any>, tools?: Record<string, any>): Promise<ParsedWorkflow>;
+/**
+ * Validate YAML workflow definition
+ */
+export declare function validateWorkflowDefinition(definition: YAMLWorkflowDefinition): string[];

package/dist/workflows/yaml-parser.js

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * YAML Workflow Parser
+ * Parse YAML workflow definitions into executable workflows
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseYAMLWorkflow = parseYAMLWorkflow;
+exports.createWorkflowFromYAML = createWorkflowFromYAML;
+exports.loadWorkflowFromFile = loadWorkflowFromFile;
+exports.validateWorkflowDefinition = validateWorkflowDefinition;
+const index_1 = require("./index");
+/**
+ * Parse YAML string into workflow definition
+ */
+function parseYAMLWorkflow(yamlContent) {
+    // Simple YAML parser for workflow definitions
+    // For production, use js-yaml package
+    const lines = yamlContent.split('\n');
+    const result = {
+        name: '',
+        steps: []
+    };
+    let currentStep = null;
+    let indent = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const currentIndent = line.search(/\S/);
+        // Parse key-value pairs
+        const colonIndex = trimmed.indexOf(':');
+        if (colonIndex === -1)
+            continue;
+        const key = trimmed.substring(0, colonIndex).trim();
+        const value = trimmed.substring(colonIndex + 1).trim();
+        if (currentIndent === 0) {
+            // Top-level keys
+            if (key === 'name')
+                result.name = value;
+            else if (key === 'description')
+                result.description = value;
+            else if (key === 'version')
+                result.version = value;
+            else if (key === 'steps') {
+                // Steps array starts
+                indent = currentIndent;
+            }
+        }
+        else if (trimmed.startsWith('- name:')) {
+            // New step
+            if (currentStep && currentStep.name) {
+                result.steps.push(currentStep);
+            }
+            currentStep = {
+                name: value,
+                type: 'agent'
+            };
+        }
+        else if (currentStep) {
+            // Step properties
+            if (key === 'type')
+                currentStep.type = value;
+            else if (key === 'agent')
+                currentStep.agent = value;
+            else if (key === 'tool')
+                currentStep.tool = value;
+            else if (key === 'input')
+                currentStep.input = value;
+            else if (key === 'output')
+                currentStep.output = value;
+            else if (key === 'condition')
+                currentStep.condition = value;
+            else if (key === 'onError')
+                currentStep.onError = value;
+            else if (key === 'maxRetries')
+                currentStep.maxRetries = parseInt(value);
+            else if (key === 'timeout')
+                currentStep.timeout = parseInt(value);
+            else if (key === 'loopCondition')
+                currentStep.loopCondition = value;
+            else if (key === 'maxIterations')
+                currentStep.maxIterations = parseInt(value);
+        }
+    }
+    // Add last step
+    if (currentStep && currentStep.name) {
+        result.steps.push(currentStep);
+    }
+    return result;
+}
+/**
+ * Create executable workflow from YAML definition
+ */
+function createWorkflowFromYAML(definition, agents = {}, tools = {}) {
+    const errors = [];
+    const workflow = new index_1.Workflow(definition.name);
+    for (const stepDef of definition.steps) {
+        try {
+            const stepConfig = createStepConfig(stepDef, agents, tools, errors);
+            if (stepConfig) {
+                workflow.addStep(stepConfig);
+            }
+        }
+        catch (error) {
+            errors.push(`Error creating step ${stepDef.name}: ${error.message}`);
+        }
+    }
+    return { workflow, definition, errors };
+}
+function createStepConfig(stepDef, agents, tools, errors) {
+    const { name, type, agent, tool, onError, maxRetries, timeout, condition } = stepDef;
+    let execute;
+    switch (type) {
+        case 'agent':
+            if (!agent) {
+                errors.push(`Step ${name}: agent type requires 'agent' field`);
+                return null;
+            }
+            const agentInstance = agents[agent];
+            if (!agentInstance) {
+                errors.push(`Step ${name}: agent '${agent}' not found`);
+                return null;
+            }
+            execute = async (input) => {
+                if (typeof agentInstance.chat === 'function') {
+                    return agentInstance.chat(typeof input === 'string' ? input : JSON.stringify(input));
+                }
+                return agentInstance(input);
+            };
+            break;
+        case 'tool':
+            if (!tool) {
+                errors.push(`Step ${name}: tool type requires 'tool' field`);
+                return null;
+            }
+            const toolInstance = tools[tool];
+            if (!toolInstance) {
+                errors.push(`Step ${name}: tool '${tool}' not found`);
+                return null;
+            }
+            execute = async (input) => {
+                if (typeof toolInstance.execute === 'function') {
+                    return toolInstance.execute(input);
+                }
+                if (typeof toolInstance.run === 'function') {
+                    return toolInstance.run(input);
+                }
+                return toolInstance(input);
+            };
+            break;
+        case 'condition':
+            execute = async (input, context) => {
+                // Evaluate condition and return input or skip
+                if (condition) {
+                    // Simple condition evaluation
+                    const result = evaluateCondition(condition, input, context);
+                    return result ? input : null;
+                }
+                return input;
+            };
+            break;
+        default:
+            execute = async (input) => input;
+    }
+    return {
+        name,
+        execute,
+        onError,
+        maxRetries,
+        timeout,
+        condition: condition ? (context) => evaluateCondition(condition, null, context) : undefined
+    };
+}
+function evaluateCondition(condition, input, context) {
+    // Simple condition evaluation
+    // Supports: "result.success", "input.length > 0", etc.
+    try {
+        // Create a safe evaluation context
+        const evalContext = {
+            input,
+            context,
+            result: context?.get?.('lastResult'),
+            ...context?.metadata
+        };
+        // Simple expression evaluation
+        if (condition.includes('===')) {
+            const [left, right] = condition.split('===').map(s => s.trim());
+            return getNestedValue(evalContext, left) === parseValue(right);
+        }
+        if (condition.includes('!==')) {
+            const [left, right] = condition.split('!==').map(s => s.trim());
+            return getNestedValue(evalContext, left) !== parseValue(right);
+        }
+        if (condition.includes('>')) {
+            const [left, right] = condition.split('>').map(s => s.trim());
+            return getNestedValue(evalContext, left) > parseValue(right);
+        }
+        if (condition.includes('<')) {
+            const [left, right] = condition.split('<').map(s => s.trim());
+            return getNestedValue(evalContext, left) < parseValue(right);
+        }
+        // Boolean check
+        return !!getNestedValue(evalContext, condition);
+    }
+    catch {
+        return false;
+    }
+}
+function getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key) => current?.[key], obj);
+}
+function parseValue(value) {
+    value = value.trim();
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (value === 'null')
+        return null;
+    if (value.startsWith('"') && value.endsWith('"'))
+        return value.slice(1, -1);
+    if (value.startsWith("'") && value.endsWith("'"))
+        return value.slice(1, -1);
+    const num = Number(value);
+    if (!isNaN(num))
+        return num;
+    return value;
+}
+/**
+ * Load workflow from YAML file
+ */
+async function loadWorkflowFromFile(filePath, agents = {}, tools = {}) {
+    const fs = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+    const content = await fs.readFile(filePath, 'utf-8');
+    const definition = parseYAMLWorkflow(content);
+    return createWorkflowFromYAML(definition, agents, tools);
+}
+/**
+ * Validate YAML workflow definition
+ */
+function validateWorkflowDefinition(definition) {
+    const errors = [];
+    if (!definition.name) {
+        errors.push('Workflow must have a name');
+    }
+    if (!definition.steps || definition.steps.length === 0) {
+        errors.push('Workflow must have at least one step');
+    }
+    const stepNames = new Set();
+    for (const step of definition.steps) {
+        if (!step.name) {
+            errors.push('Each step must have a name');
+        }
+        else if (stepNames.has(step.name)) {
+            errors.push(`Duplicate step name: ${step.name}`);
+        }
+        else {
+            stepNames.add(step.name);
+        }
+        if (!step.type) {
+            errors.push(`Step ${step.name}: must have a type`);
+        }
+        if (step.type === 'agent' && !step.agent) {
+            errors.push(`Step ${step.name}: agent type requires 'agent' field`);
+        }
+        if (step.type === 'tool' && !step.tool) {
+            errors.push(`Step ${step.name}: tool type requires 'tool' field`);
+        }
+    }
+    return errors;
+}

package/package.json

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