overai 1.4.0

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/llm/backend-resolver.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Backend Resolver - Unified LLM backend resolution with AI SDK preference
+ *
+ * Resolution order:
+ * 1. AI SDK backend (if installed and enabled)
+ * 2. Native provider registry (OpenAI, Anthropic, Google)
+ * 3. Error with actionable guidance
+ *
+ * Environment variables:
+ * - PRAISONAI_BACKEND: 'ai-sdk' | 'native' | 'auto' (default: 'auto')
+ */
+import type { LLMProvider, ProviderConfig } from './providers/types';
+export type BackendSource = 'ai-sdk' | 'native' | 'custom' | 'legacy';
+export interface BackendResolutionResult {
+    provider: LLMProvider;
+    source: BackendSource;
+    providerId: string;
+    modelId: string;
+    warnings?: string[];
+}
+export interface ResolveBackendOptions {
+    /** Force a specific backend: 'ai-sdk' | 'native' | 'auto' (default: 'auto') */
+    backend?: 'ai-sdk' | 'native' | 'auto';
+    /** Provider configuration (API keys, timeouts, etc.) */
+    config?: ProviderConfig;
+    /** Attribution context for multi-agent tracing */
+    attribution?: {
+        agentId?: string;
+        runId?: string;
+        sessionId?: string;
+    };
+}
+/**
+ * Check if AI SDK is available (installed)
+ * Result is cached after first check
+ */
+export declare function isAISDKAvailable(): Promise<boolean>;
+/**
+ * Reset the AI SDK availability cache (for testing)
+ */
+export declare function resetAISDKAvailabilityCache(): void;
+/**
+ * Get the preferred backend from environment
+ */
+export declare function getPreferredBackend(): 'ai-sdk' | 'native' | 'auto';
+/**
+ * Parse model string into provider and model ID
+ */
+export declare function parseModelString(model: string): {
+    providerId: string;
+    modelId: string;
+};
+/**
+ * Resolve the best available backend for a model
+ *
+ * @param modelString - Model string in format "provider/model" or just "model"
+ * @param options - Resolution options
+ * @returns Backend resolution result with provider instance
+ *
+ * @example
+ * ```typescript
+ * const { provider, source } = await resolveBackend('openai/gpt-4o-mini');
+ * const result = await provider.generateText({ messages: [...] });
+ * ```
+ */
+export declare function resolveBackend(modelString: string, options?: ResolveBackendOptions): Promise<BackendResolutionResult>;
+/**
+ * Resolve backend synchronously using cached availability
+ * Only works if isAISDKAvailable() has been called before
+ * Falls back to native if cache is not populated
+ */
+export declare function resolveBackendSync(modelString: string, options?: ResolveBackendOptions): BackendResolutionResult;
+/**
+ * Get default model string
+ */
+export declare function getDefaultModel(): string;
+export type { LLMProvider, ProviderConfig };

package/dist/llm/backend-resolver.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * Backend Resolver - Unified LLM backend resolution with AI SDK preference
+ *
+ * Resolution order:
+ * 1. AI SDK backend (if installed and enabled)
+ * 2. Native provider registry (OpenAI, Anthropic, Google)
+ * 3. Error with actionable guidance
+ *
+ * Environment variables:
+ * - PRAISONAI_BACKEND: 'ai-sdk' | 'native' | 'auto' (default: 'auto')
+ */
+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.isAISDKAvailable = isAISDKAvailable;
+exports.resetAISDKAvailabilityCache = resetAISDKAvailabilityCache;
+exports.getPreferredBackend = getPreferredBackend;
+exports.parseModelString = parseModelString;
+exports.resolveBackend = resolveBackend;
+exports.resolveBackendSync = resolveBackendSync;
+exports.getDefaultModel = getDefaultModel;
+// Cached availability check
+let _aiSdkAvailable = null;
+let _aiSdkCheckPromise = null;
+/**
+ * Check if AI SDK is available (installed)
+ * Result is cached after first check
+ */
+async function isAISDKAvailable() {
+    if (_aiSdkAvailable !== null) {
+        return _aiSdkAvailable;
+    }
+    if (_aiSdkCheckPromise) {
+        return _aiSdkCheckPromise;
+    }
+    _aiSdkCheckPromise = (async () => {
+        try {
+            // Dynamic import to avoid loading if not needed
+            const moduleName = 'ai';
+            await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s)));
+            _aiSdkAvailable = true;
+            return true;
+        }
+        catch {
+            _aiSdkAvailable = false;
+            return false;
+        }
+    })();
+    return _aiSdkCheckPromise;
+}
+/**
+ * Reset the AI SDK availability cache (for testing)
+ */
+function resetAISDKAvailabilityCache() {
+    _aiSdkAvailable = null;
+    _aiSdkCheckPromise = null;
+}
+/**
+ * Get the preferred backend from environment
+ */
+function getPreferredBackend() {
+    const env = process.env.PRAISONAI_BACKEND?.toLowerCase();
+    if (env === 'ai-sdk' || env === 'aisdk')
+        return 'ai-sdk';
+    if (env === 'native' || env === 'legacy')
+        return 'native';
+    return 'auto';
+}
+/**
+ * Parse model string into provider and model ID
+ */
+function parseModelString(model) {
+    if (model.includes('/')) {
+        const [providerId, ...rest] = model.split('/');
+        return { providerId: providerId.toLowerCase(), modelId: rest.join('/') };
+    }
+    // Default to OpenAI for common model prefixes
+    if (model.startsWith('gpt-') || model.startsWith('o1') || model.startsWith('o3')) {
+        return { providerId: 'openai', modelId: model };
+    }
+    if (model.startsWith('claude-')) {
+        return { providerId: 'anthropic', modelId: model };
+    }
+    if (model.startsWith('gemini-')) {
+        return { providerId: 'google', modelId: model };
+    }
+    // Default to OpenAI
+    return { providerId: 'openai', modelId: model };
+}
+/**
+ * Resolve the best available backend for a model
+ *
+ * @param modelString - Model string in format "provider/model" or just "model"
+ * @param options - Resolution options
+ * @returns Backend resolution result with provider instance
+ *
+ * @example
+ * ```typescript
+ * const { provider, source } = await resolveBackend('openai/gpt-4o-mini');
+ * const result = await provider.generateText({ messages: [...] });
+ * ```
+ */
+async function resolveBackend(modelString, options = {}) {
+    const { providerId, modelId } = parseModelString(modelString);
+    const preferredBackend = options.backend || getPreferredBackend();
+    const warnings = [];
+    // Try AI SDK first if preferred or auto
+    if (preferredBackend === 'ai-sdk' || preferredBackend === 'auto') {
+        const aiSdkAvailable = await isAISDKAvailable();
+        if (aiSdkAvailable) {
+            try {
+                // Lazy import AI SDK backend
+                const { createAISDKBackend } = await Promise.resolve().then(() => __importStar(require('./providers/ai-sdk')));
+                const backend = createAISDKBackend(modelString, {
+                    ...options.config,
+                    attribution: options.attribution ? {
+                        agentId: options.attribution.agentId,
+                        runId: options.attribution.runId,
+                        sessionId: options.attribution.sessionId,
+                    } : undefined,
+                });
+                return {
+                    provider: backend,
+                    source: 'ai-sdk',
+                    providerId,
+                    modelId,
+                    warnings: warnings.length > 0 ? warnings : undefined,
+                };
+            }
+            catch (error) {
+                if (preferredBackend === 'ai-sdk') {
+                    // User explicitly requested AI SDK, throw error
+                    throw new Error(`AI SDK backend failed for '${modelString}': ${error.message}. ` +
+                        `Set PRAISONAI_BACKEND=native to use native providers.`);
+                }
+                // Auto mode: fall through to native
+                warnings.push(`AI SDK failed: ${error.message}, falling back to native provider`);
+            }
+        }
+        else if (preferredBackend === 'ai-sdk') {
+            throw new Error(`AI SDK is not installed but PRAISONAI_BACKEND=ai-sdk is set. ` +
+                `Install with: npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google`);
+        }
+    }
+    // Try native provider registry
+    try {
+        const { createProvider } = await Promise.resolve().then(() => __importStar(require('./providers')));
+        const provider = createProvider(modelString, options.config);
+        return {
+            provider,
+            source: 'native',
+            providerId,
+            modelId,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    catch (error) {
+        throw new Error(`Cannot resolve backend for '${modelString}'. ` +
+            `Neither AI SDK nor native provider available. ` +
+            `Install AI SDK: npm install ai @ai-sdk/${providerId} ` +
+            `or check your provider configuration. ` +
+            `Original error: ${error.message}`);
+    }
+}
+/**
+ * Resolve backend synchronously using cached availability
+ * Only works if isAISDKAvailable() has been called before
+ * Falls back to native if cache is not populated
+ */
+function resolveBackendSync(modelString, options = {}) {
+    const { providerId, modelId } = parseModelString(modelString);
+    const preferredBackend = options.backend || getPreferredBackend();
+    // If AI SDK availability is cached and available, try it first
+    if (_aiSdkAvailable === true && (preferredBackend === 'ai-sdk' || preferredBackend === 'auto')) {
+        try {
+            // This will throw if AI SDK module is not already loaded
+            const aiSdk = require('./providers/ai-sdk');
+            const backend = aiSdk.createAISDKBackend(modelString, {
+                ...options.config,
+                attribution: options.attribution,
+            });
+            return {
+                provider: backend,
+                source: 'ai-sdk',
+                providerId,
+                modelId,
+            };
+        }
+        catch {
+            // Fall through to native
+        }
+    }
+    // Use native provider
+    const { createProvider } = require('./providers');
+    const provider = createProvider(modelString, options.config);
+    return {
+        provider,
+        source: 'native',
+        providerId,
+        modelId,
+    };
+}
+/**
+ * Get default model string
+ */
+function getDefaultModel() {
+    return process.env.OPENAI_MODEL_NAME ||
+        process.env.PRAISONAI_MODEL ||
+        'openai/gpt-4o-mini';
+}

package/dist/llm/embeddings.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Embeddings - AI SDK-backed embedding utilities
+ *
+ * Provides embedding functionality with AI SDK preference and native fallback.
+ * Integrates with existing EmbeddingProvider interface in knowledge/rag.ts and memory/memory.ts
+ */
+import type { EmbeddingProvider } from '../knowledge/rag';
+export interface EmbeddingOptions {
+    /** Model to use for embeddings (default: text-embedding-3-small) */
+    model?: string;
+    /** Provider to use (default: openai) */
+    provider?: string;
+    /** Maximum retries (default: 2) */
+    maxRetries?: number;
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Additional headers */
+    headers?: Record<string, string>;
+    /** Force specific backend: 'ai-sdk' | 'native' | 'auto' */
+    backend?: 'ai-sdk' | 'native' | 'auto';
+}
+export interface EmbeddingResult {
+    embedding: number[];
+    usage?: {
+        tokens: number;
+    };
+}
+export interface EmbeddingBatchResult {
+    embeddings: number[][];
+    usage?: {
+        tokens: number;
+    };
+}
+/**
+ * Get the default embedding model for a provider
+ */
+export declare function getDefaultEmbeddingModel(provider?: string): string;
+/**
+ * Parse embedding model string into provider and model
+ */
+export declare function parseEmbeddingModel(model: string): {
+    provider: string;
+    model: string;
+};
+/**
+ * Embed a single text using AI SDK (preferred) or native provider
+ */
+export declare function embed(text: string, options?: EmbeddingOptions): Promise<EmbeddingResult>;
+/**
+ * Embed multiple texts using AI SDK (preferred) or native provider
+ */
+export declare function embedMany(texts: string[], options?: EmbeddingOptions): Promise<EmbeddingBatchResult>;
+/**
+ * Create an EmbeddingProvider that uses AI SDK
+ * Compatible with KnowledgeBase and Memory interfaces
+ */
+export declare function createEmbeddingProvider(options?: EmbeddingOptions): EmbeddingProvider;
+/**
+ * Cosine similarity between two vectors
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Euclidean distance between two vectors
+ */
+export declare function euclideanDistance(a: number[], b: number[]): number;
+export type { EmbeddingProvider };