@juspay/neurolink 9.32.0 → 9.33.0

package/dist/client/rag/reranker/RerankerRegistry.js

@@ -1,402 +0,0 @@
-/**
- * Reranker Registry
- *
- * Centralized registry for all reranker implementations with metadata
- * and discovery capabilities. Follows the BaseRegistry pattern.
- */
-import { BaseRegistry } from "../../core/infrastructure/index.js";
-import { logger } from "../../utils/logger.js";
-import { RAGErrorCodes, RerankerError } from "../errors/RAGError.js";
-/**
- * Default reranker metadata entries
- */
-const DEFAULT_RERANKER_METADATA = {
-    llm: {
-        description: "LLM-powered semantic reranking with multi-factor scoring",
-        defaultConfig: {
-            topK: 3,
-            weights: { semantic: 0.4, vector: 0.4, position: 0.2 },
-        },
-        supportedOptions: ["model", "provider", "topK", "weights"],
-        useCases: [
-            "High-quality semantic reranking",
-            "Complex query understanding",
-            "Context-aware scoring",
-        ],
-        aliases: ["semantic", "ai", "model-based"],
-        requiresModel: true,
-        requiresExternalAPI: false,
-    },
-    "cross-encoder": {
-        description: "Cross-encoder model for query-document relevance scoring",
-        defaultConfig: {
-            topK: 3,
-            model: "ms-marco-MiniLM-L-6-v2",
-        },
-        supportedOptions: ["model", "topK"],
-        useCases: [
-            "High-precision reranking",
-            "Search result refinement",
-            "Academic/research applications",
-        ],
-        aliases: ["cross", "encoder", "bi-encoder"],
-        requiresModel: true,
-        requiresExternalAPI: false,
-    },
-    cohere: {
-        description: "Cohere Rerank API for production-grade relevance scoring",
-        defaultConfig: {
-            topK: 3,
-            model: "rerank-v3.5",
-        },
-        supportedOptions: ["model", "topK", "apiKey"],
-        useCases: [
-            "Production search systems",
-            "Enterprise applications",
-            "High-volume reranking",
-        ],
-        aliases: ["cohere-rerank", "cohere-api"],
-        requiresModel: false,
-        requiresExternalAPI: true,
-    },
-    simple: {
-        description: "Position and vector score-based reranking (no LLM required)",
-        defaultConfig: {
-            topK: 3,
-            weights: { vector: 0.8, position: 0.2 },
-        },
-        supportedOptions: ["topK", "weights"],
-        useCases: [
-            "Fast reranking",
-            "Low-latency requirements",
-            "When LLM is unavailable",
-        ],
-        aliases: ["fast", "basic", "position-based"],
-        requiresModel: false,
-        requiresExternalAPI: false,
-    },
-    batch: {
-        description: "Batch LLM reranking for efficient multi-document scoring",
-        defaultConfig: {
-            topK: 3,
-            weights: { semantic: 0.4, vector: 0.4, position: 0.2 },
-        },
-        supportedOptions: ["model", "provider", "topK", "weights"],
-        useCases: [
-            "Large result sets",
-            "Cost-efficient LLM usage",
-            "Batch processing pipelines",
-        ],
-        aliases: ["batch-llm", "efficient", "bulk"],
-        requiresModel: true,
-        requiresExternalAPI: false,
-    },
-};
-/**
- * Reranker Registry
- *
- * Manages registration and discovery of all reranker implementations.
- * Extends BaseRegistry for consistent lifecycle management.
- */
-export class RerankerRegistry extends BaseRegistry {
-    static instance = null;
-    aliasMap = new Map();
-    constructor() {
-        super();
-    }
-    /**
-     * Get singleton instance
-     */
-    static getInstance() {
-        if (!RerankerRegistry.instance) {
-            RerankerRegistry.instance = new RerankerRegistry();
-        }
-        return RerankerRegistry.instance;
-    }
-    /**
-     * Reset singleton (for testing)
-     */
-    static resetInstance() {
-        if (RerankerRegistry.instance) {
-            RerankerRegistry.instance.clear();
-            RerankerRegistry.instance = null;
-        }
-    }
-    /**
-     * Register all built-in rerankers
-     */
-    async registerAll() {
-        // Import reranker functions
-        const rerankerModule = await import("./reranker.js");
-        // Register LLM reranker
-        this.registerReranker("llm", async () => this.createLLMRerankerInstance(rerankerModule.rerank), DEFAULT_RERANKER_METADATA.llm);
-        // Register cross-encoder reranker
-        this.registerReranker("cross-encoder", async () => this.createCrossEncoderInstance(rerankerModule.CrossEncoderReranker), DEFAULT_RERANKER_METADATA["cross-encoder"]);
-        // Register Cohere reranker
-        this.registerReranker("cohere", async () => this.createCohereInstance(rerankerModule.CohereRelevanceScorer), DEFAULT_RERANKER_METADATA.cohere);
-        // Register simple reranker
-        this.registerReranker("simple", async () => this.createSimpleRerankerInstance(rerankerModule.simpleRerank), DEFAULT_RERANKER_METADATA.simple);
-        // Register batch reranker
-        this.registerReranker("batch", async () => this.createBatchRerankerInstance(rerankerModule.batchRerank), DEFAULT_RERANKER_METADATA.batch);
-        logger.debug(`[RerankerRegistry] Registered ${this.items.size} reranker types`);
-    }
-    /**
-     * Create LLM reranker instance wrapper
-     */
-    createLLMRerankerInstance(_rerankFn) {
-        return {
-            type: "llm",
-            async rerank() {
-                throw new RerankerError("LLM reranker requires model provider. Use RerankerFactory.createReranker() instead.", {
-                    rerankerType: "llm",
-                });
-            },
-        };
-    }
-    /**
-     * Create cross-encoder instance wrapper
-     */
-    createCrossEncoderInstance(CrossEncoderClass) {
-        const encoder = new CrossEncoderClass();
-        return {
-            type: "cross-encoder",
-            async rerank(results, query, options) {
-                const documents = results.map((r) => r.text || r.metadata?.text || "");
-                const scores = await encoder.rerank(query, documents);
-                const topK = options?.topK ?? 3;
-                return scores
-                    .map((s) => ({
-                    result: results[s.index],
-                    score: s.score,
-                    details: {
-                        semantic: s.score,
-                        vector: results[s.index].score ?? 0,
-                        position: 1 - s.index / results.length,
-                    },
-                }))
-                    .sort((a, b) => b.score - a.score)
-                    .slice(0, topK);
-            },
-        };
-    }
-    /**
-     * Create Cohere instance wrapper
-     */
-    createCohereInstance(CohereClass) {
-        const scorer = new CohereClass();
-        return {
-            type: "cohere",
-            async rerank(results, query, options) {
-                const documents = results.map((r) => r.text || r.metadata?.text || "");
-                const scores = await scorer.score(query, documents);
-                const topK = options?.topK ?? 3;
-                return scores
-                    .map((s) => ({
-                    result: results[s.index],
-                    score: s.score,
-                    details: {
-                        semantic: s.score,
-                        vector: results[s.index].score ?? 0,
-                        position: 1 - s.index / results.length,
-                    },
-                }))
-                    .sort((a, b) => b.score - a.score)
-                    .slice(0, topK);
-            },
-        };
-    }
-    /**
-     * Create simple reranker instance wrapper
-     */
-    createSimpleRerankerInstance(simpleRerankFn) {
-        return {
-            type: "simple",
-            async rerank(results, _query, options) {
-                return simpleRerankFn(results, {
-                    topK: options?.topK,
-                    vectorWeight: options?.weights?.vector,
-                    positionWeight: options?.weights?.position,
-                });
-            },
-        };
-    }
-    /**
-     * Create batch reranker instance wrapper
-     */
-    createBatchRerankerInstance(_batchRerankFn) {
-        return {
-            type: "batch",
-            async rerank() {
-                throw new RerankerError("Batch reranker requires model provider. Use RerankerFactory.createReranker() instead.", {
-                    rerankerType: "batch",
-                });
-            },
-        };
-    }
-    /**
-     * Register a reranker with aliases
-     */
-    registerReranker(type, factory, metadata) {
-        this.register(type, factory, metadata.aliases, { metadata });
-        // Register aliases in local alias map for type resolution
-        for (const alias of metadata.aliases) {
-            this.aliasMap.set(alias.toLowerCase(), type);
-            logger.debug(`[RerankerRegistry] Registered alias '${alias}' -> '${type}'`);
-        }
-    }
-    /**
-     * Resolve type from alias
-     */
-    resolveType(nameOrAlias) {
-        const lower = nameOrAlias.toLowerCase();
-        // Check if it's a direct type
-        if (this.items.has(lower)) {
-            return lower;
-        }
-        // Check aliases
-        const resolved = this.aliasMap.get(lower);
-        if (resolved) {
-            return resolved;
-        }
-        throw new RerankerError(`Unknown reranker type: '${nameOrAlias}'. Available types: ${this.list()
-            .map((item) => item.id)
-            .join(", ")}`, {
-            code: RAGErrorCodes.RERANKER_NOT_FOUND,
-            rerankerType: nameOrAlias,
-            details: {
-                requestedType: nameOrAlias,
-                availableTypes: this.list().map((item) => item.id),
-            },
-        });
-    }
-    /**
-     * Get a reranker by type or alias
-     */
-    async getReranker(typeOrAlias) {
-        await this.ensureInitialized();
-        const type = this.resolveType(typeOrAlias);
-        const reranker = await this.get(type);
-        if (!reranker) {
-            throw new RerankerError(`Reranker not found: ${type}`, {
-                code: RAGErrorCodes.RERANKER_NOT_FOUND,
-                rerankerType: type,
-                details: { type },
-            });
-        }
-        return reranker;
-    }
-    /**
-     * Get list of available reranker types
-     */
-    async getAvailableRerankers() {
-        await this.ensureInitialized();
-        return this.list().map((item) => item.id);
-    }
-    /**
-     * Get metadata for a specific reranker
-     */
-    getRerankerMetadata(typeOrAlias) {
-        const type = this.resolveType(typeOrAlias);
-        const entry = this.list().find((item) => item.id === type);
-        return entry?.metadata;
-    }
-    /**
-     * Get all aliases for a type
-     */
-    getAliasesForType(type) {
-        const metadata = DEFAULT_RERANKER_METADATA[type];
-        return metadata?.aliases ?? [];
-    }
-    /**
-     * Get all registered aliases
-     */
-    getAllAliases() {
-        return new Map(this.aliasMap);
-    }
-    /**
-     * Check if a type or alias exists
-     */
-    hasReranker(typeOrAlias) {
-        try {
-            this.resolveType(typeOrAlias);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    /**
-     * Get rerankers by use case
-     */
-    getRerankersByUseCase(useCase) {
-        const matches = [];
-        const useCaseLower = useCase.toLowerCase();
-        for (const [type, metadata] of Object.entries(DEFAULT_RERANKER_METADATA)) {
-            const hasMatchingUseCase = metadata.useCases.some((uc) => uc.toLowerCase().includes(useCaseLower));
-            if (hasMatchingUseCase) {
-                matches.push(type);
-            }
-        }
-        return matches;
-    }
-    /**
-     * Get default configuration for a reranker
-     */
-    getDefaultConfig(typeOrAlias) {
-        const metadata = this.getRerankerMetadata(typeOrAlias);
-        return metadata?.defaultConfig;
-    }
-    /**
-     * Get rerankers that don't require external APIs
-     */
-    getLocalRerankers() {
-        const matches = [];
-        for (const [type, metadata] of Object.entries(DEFAULT_RERANKER_METADATA)) {
-            if (!metadata.requiresExternalAPI) {
-                matches.push(type);
-            }
-        }
-        return matches;
-    }
-    /**
-     * Get rerankers that don't require AI models
-     */
-    getModelFreeRerankers() {
-        const matches = [];
-        for (const [type, metadata] of Object.entries(DEFAULT_RERANKER_METADATA)) {
-            if (!metadata.requiresModel) {
-                matches.push(type);
-            }
-        }
-        return matches;
-    }
-    /**
-     * Clear the registry (also clears aliases)
-     */
-    clear() {
-        super.clear();
-        this.aliasMap.clear();
-    }
-}
-/**
- * Global reranker registry singleton
- */
-export const rerankerRegistry = RerankerRegistry.getInstance();
-/**
- * Convenience function to get available rerankers
- */
-export async function getAvailableRerankers() {
-    return rerankerRegistry.getAvailableRerankers();
-}
-/**
- * Convenience function to get reranker by type
- */
-export async function getReranker(typeOrAlias) {
-    return rerankerRegistry.getReranker(typeOrAlias);
-}
-/**
- * Convenience function to get reranker metadata
- */
-export function getRegisteredRerankerMetadata(typeOrAlias) {
-    return rerankerRegistry.getRerankerMetadata(typeOrAlias);
-}

package/dist/client/rag/reranker/index.js

@@ -1,9 +0,0 @@
-/**
- * Reranker Module Exports
- */
-// Factory pattern exports
-export { createReranker, getAvailableRerankerTypes, getRerankerDefaultConfig, getRerankerMetadata, RerankerFactory, rerankerFactory, } from "./RerankerFactory.js";
-// Registry pattern exports
-export { getAvailableRerankers, getRegisteredRerankerMetadata, getReranker, RerankerRegistry, rerankerRegistry, } from "./RerankerRegistry.js";
-// Core reranker functions
-export { batchRerank, CohereRelevanceScorer, CrossEncoderReranker, rerank, simpleRerank, } from "./reranker.js";

package/dist/client/rag/reranker/reranker.js

@@ -1,277 +0,0 @@
-/**
- * Reranker Implementation
- *
- * Multi-factor scoring system for reranking retrieval results.
- * Combines semantic relevance (LLM-based), vector similarity, and position.
- */
-import { logger } from "../../utils/logger.js";
-/**
- * Default scoring weights
- */
-const DEFAULT_WEIGHTS = {
-    semantic: 0.4,
-    vector: 0.4,
-    position: 0.2,
-};
-/**
- * Rerank vector search results using multi-factor scoring
- *
- * Combines three scoring factors:
- * 1. Semantic score: LLM-based relevance assessment
- * 2. Vector score: Original similarity score from vector search
- * 3. Position score: Inverse of original ranking position
- *
- * @param results - Vector search results to rerank
- * @param query - Original search query
- * @param model - Language model for semantic scoring
- * @param options - Reranking options
- * @returns Reranked results with detailed scores
- */
-export async function rerank(results, query, model, options) {
-    const { queryEmbedding: _queryEmbedding, topK = 3, weights = DEFAULT_WEIGHTS, } = options || {};
-    if (results.length === 0) {
-        return [];
-    }
-    // Validate weights sum to 1.0
-    const totalWeight = (weights.semantic || DEFAULT_WEIGHTS.semantic) +
-        (weights.vector || DEFAULT_WEIGHTS.vector) +
-        (weights.position || DEFAULT_WEIGHTS.position);
-    if (Math.abs(totalWeight - 1.0) > 0.01) {
-        logger.warn("[Reranker] Weights do not sum to 1.0, normalizing", {
-            original: weights,
-            total: totalWeight,
-        });
-    }
-    const normalizedWeights = {
-        semantic: (weights.semantic || DEFAULT_WEIGHTS.semantic) / totalWeight,
-        vector: (weights.vector || DEFAULT_WEIGHTS.vector) / totalWeight,
-        position: (weights.position || DEFAULT_WEIGHTS.position) / totalWeight,
-    };
-    const rerankedResults = [];
-    // Process results in parallel batches for efficiency
-    const batchSize = 5;
-    for (let i = 0; i < results.length; i += batchSize) {
-        const batch = results.slice(i, i + batchSize);
-        const batchPromises = batch.map(async (result, batchIndex) => {
-            const globalIndex = i + batchIndex;
-            // Calculate vector score (use existing score or 0)
-            const vectorScore = result.score ?? 0;
-            // Calculate position score (inverse of position)
-            const positionScore = 1 - globalIndex / results.length;
-            // Calculate semantic score using LLM
-            const semanticResult = await calculateSemanticScore(query, result.text || result.metadata?.text || "", model);
-            // Combine scores
-            const combinedScore = normalizedWeights.semantic * semanticResult.score +
-                normalizedWeights.vector * vectorScore +
-                normalizedWeights.position * positionScore;
-            return {
-                result,
-                score: combinedScore,
-                details: {
-                    semantic: semanticResult.score,
-                    vector: vectorScore,
-                    position: positionScore,
-                    queryAnalysis: semanticResult.analysis,
-                },
-            };
-        });
-        const batchResults = await Promise.all(batchPromises);
-        rerankedResults.push(...batchResults);
-    }
-    // Sort by combined score descending
-    rerankedResults.sort((a, b) => b.score - a.score);
-    // Return top K results
-    return rerankedResults.slice(0, topK);
-}
-/**
- * Calculate semantic relevance score using LLM
- *
- * @param query - Search query
- * @param text - Document text to score
- * @param model - Language model for scoring
- * @returns Score between 0 and 1 with optional analysis
- */
-async function calculateSemanticScore(query, text, model) {
-    const prompt = `Rate the relevance of the following text to the query on a scale of 0 to 1.
-
-Query: ${query}
-
-Text: ${text.slice(0, 1000)}
-
-Respond with only a number between 0 and 1, where:
-- 0 means completely irrelevant
-- 0.5 means somewhat relevant
-- 1 means highly relevant
-
-Score:`;
-    try {
-        const result = await model.generate({
-            prompt,
-            maxTokens: 10,
-            temperature: 0,
-        });
-        const scoreText = result?.content?.trim() || "0";
-        const score = parseFloat(scoreText);
-        if (isNaN(score) || score < 0 || score > 1) {
-            return { score: 0.5 };
-        }
-        return { score };
-    }
-    catch (error) {
-        logger.warn("[Reranker] Semantic scoring failed, using default", {
-            error: error instanceof Error ? error.message : String(error),
-        });
-        return { score: 0.5 };
-    }
-}
-/**
- * Batch rerank with optimized LLM calls
- * Scores multiple documents in a single prompt for efficiency
- *
- * @param results - Results to rerank
- * @param query - Search query
- * @param model - Language model
- * @param options - Reranking options
- * @returns Reranked results
- */
-export async function batchRerank(results, query, model, options) {
-    const { topK = 3, weights = DEFAULT_WEIGHTS } = options || {};
-    if (results.length === 0) {
-        return [];
-    }
-    // Normalize weights
-    const totalWeight = (weights.semantic || DEFAULT_WEIGHTS.semantic) +
-        (weights.vector || DEFAULT_WEIGHTS.vector) +
-        (weights.position || DEFAULT_WEIGHTS.position);
-    const normalizedWeights = {
-        semantic: (weights.semantic || DEFAULT_WEIGHTS.semantic) / totalWeight,
-        vector: (weights.vector || DEFAULT_WEIGHTS.vector) / totalWeight,
-        position: (weights.position || DEFAULT_WEIGHTS.position) / totalWeight,
-    };
-    // Build batch scoring prompt
-    const documentsText = results
-        .map((r, i) => `[${i + 1}] ${(r.text || r.metadata?.text || "").slice(0, 300)}`)
-        .join("\n\n");
-    const prompt = `Rate the relevance of each document to the query on a scale of 0 to 1.
-
-Query: ${query}
-
-Documents:
-${documentsText}
-
-For each document, provide a score between 0 and 1.
-Respond with only the scores, one per line, in order:`;
-    try {
-        const result = await model.generate({
-            prompt,
-            maxTokens: 50,
-            temperature: 0,
-        });
-        // Parse scores from response
-        const scoreLines = (result?.content || "")
-            .trim()
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0);
-        const semanticScores = [];
-        for (let i = 0; i < results.length; i++) {
-            const scoreLine = scoreLines[i];
-            if (scoreLine) {
-                const score = parseFloat(scoreLine.match(/[\d.]+/)?.[0] || "0.5");
-                semanticScores.push(isNaN(score) || score < 0 || score > 1 ? 0.5 : score);
-            }
-            else {
-                semanticScores.push(0.5);
-            }
-        }
-        // Calculate combined scores
-        const rerankedResults = results.map((result, i) => {
-            const vectorScore = result.score ?? 0;
-            const positionScore = 1 - i / results.length;
-            const semanticScore = semanticScores[i] ?? 0.5;
-            const combinedScore = normalizedWeights.semantic * semanticScore +
-                normalizedWeights.vector * vectorScore +
-                normalizedWeights.position * positionScore;
-            return {
-                result,
-                score: combinedScore,
-                details: {
-                    semantic: semanticScore,
-                    vector: vectorScore,
-                    position: positionScore,
-                },
-            };
-        });
-        // Sort and return top K
-        rerankedResults.sort((a, b) => b.score - a.score);
-        return rerankedResults.slice(0, topK);
-    }
-    catch (error) {
-        logger.warn("[Reranker] Batch scoring failed, using individual scoring", {
-            error: error instanceof Error ? error.message : String(error),
-        });
-        // Fall back to individual scoring
-        return rerank(results, query, model, options);
-    }
-}
-/**
- * Simple position-based reranker (no LLM required)
- * Uses only vector score and position
- *
- * @param results - Results to rerank
- * @param options - Reranking options
- * @returns Reranked results
- */
-export function simpleRerank(results, options) {
-    const { topK = 3, vectorWeight = 0.8, positionWeight = 0.2 } = options || {};
-    const totalWeight = vectorWeight + positionWeight;
-    const normalizedVectorWeight = vectorWeight / totalWeight;
-    const normalizedPositionWeight = positionWeight / totalWeight;
-    const rerankedResults = results.map((result, i) => {
-        const vectorScore = result.score ?? 0;
-        const positionScore = 1 - i / results.length;
-        const combinedScore = normalizedVectorWeight * vectorScore +
-            normalizedPositionWeight * positionScore;
-        return {
-            result,
-            score: combinedScore,
-            details: {
-                semantic: 0,
-                vector: vectorScore,
-                position: positionScore,
-            },
-        };
-    });
-    rerankedResults.sort((a, b) => b.score - a.score);
-    return rerankedResults.slice(0, topK);
-}
-/**
- * Cohere-style relevance scorer interface
- * Placeholder for integration with Cohere's rerank API
- */
-export class CohereRelevanceScorer {
-    modelName;
-    constructor(modelName = "rerank-v3.5") {
-        this.modelName = modelName;
-    }
-    async score(_query, _documents) {
-        // Placeholder - would use Cohere's rerank API
-        throw new Error("CohereRelevanceScorer requires Cohere API integration. " +
-            "Install @cohere-ai/cohere and provide API key.");
-    }
-}
-/**
- * Cross-encoder style reranker interface
- * Placeholder for integration with cross-encoder models
- */
-export class CrossEncoderReranker {
-    modelName;
-    constructor(modelName = "ms-marco-MiniLM-L-6-v2") {
-        this.modelName = modelName;
-    }
-    async rerank(_query, _documents) {
-        // Placeholder - would use cross-encoder model
-        throw new Error("CrossEncoderReranker requires a cross-encoder model. " +
-            "Consider using the LLM-based rerank function instead.");
-    }
-}