@juspay/neurolink 9.30.0 → 9.31.0

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

@@ -0,0 +1,402 @@
+/**
+ * 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);
+        // Register aliases
+        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

@@ -0,0 +1,9 @@
+/**
+ * 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

@@ -0,0 +1,277 @@
+/**
+ * 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.");
+    }
+}