@juspay/neurolink 11.13.0 → 11.13.2

package/dist/lib/evaluation/scorers/baseScorer.js

@@ -1,233 +0,0 @@
-/**
- * @file Abstract base scorer class providing common functionality
- * All scorers extend this class for consistent behavior
- */
-import { withTimeout, ErrorFactory } from "../../utils/errorHandling.js";
-import { logger } from "../../utils/logger.js";
-/**
- * Default score scale (0-10)
- */
-export const DEFAULT_SCORE_SCALE = {
-    min: 0,
-    max: 10,
-    precision: 2,
-};
-/**
- * Default scorer configuration
- */
-export const DEFAULT_SCORER_CONFIG = {
-    enabled: true,
-    threshold: 0.7,
-    weight: 1.0,
-    timeout: 30000,
-    retries: 2,
-};
-/**
- * Abstract base class for all scorers
- * Provides common functionality and enforces interface compliance
- */
-export class BaseScorer {
-    _config;
-    _metadata;
-    constructor(metadata, config) {
-        this._metadata = metadata;
-        this._config = {
-            ...DEFAULT_SCORER_CONFIG,
-            ...metadata.defaultConfig,
-            ...config,
-        };
-    }
-    /**
-     * Get scorer metadata
-     */
-    get metadata() {
-        return this._metadata;
-    }
-    /**
-     * Get current configuration
-     */
-    get config() {
-        return this._config;
-    }
-    /**
-     * Validate input has required fields
-     */
-    validateInput(input) {
-        const errors = [];
-        for (const field of this._metadata.requiredInputs) {
-            const value = input[field];
-            if (value === undefined || value === null) {
-                errors.push(`Missing required input: ${field}`);
-            }
-        }
-        // Check for empty strings in required text fields
-        if (this._metadata.requiredInputs.includes("query") &&
-            typeof input.query === "string" &&
-            !input.query.trim()) {
-            errors.push("Query cannot be empty");
-        }
-        if (this._metadata.requiredInputs.includes("response") &&
-            typeof input.response === "string" &&
-            !input.response.trim()) {
-            errors.push("Response cannot be empty");
-        }
-        // Check context array is not empty if required
-        if (this._metadata.requiredInputs.includes("context") &&
-            input.context !== undefined) {
-            if (!Array.isArray(input.context) || input.context.length === 0) {
-                errors.push("Context must be a non-empty array");
-            }
-        }
-        return {
-            valid: errors.length === 0,
-            errors,
-        };
-    }
-    /**
-     * Update configuration
-     */
-    configure(config) {
-        this._config = {
-            ...this._config,
-            ...config,
-        };
-        logger.debug(`Scorer ${this._metadata.id} reconfigured`, {
-            config: this._config,
-        });
-    }
-    /**
-     * Normalize a score to 0-1 scale
-     */
-    normalizeScore(score, scale = DEFAULT_SCORE_SCALE) {
-        // Validate inputs are finite
-        if (!Number.isFinite(score) ||
-            !Number.isFinite(scale.min) ||
-            !Number.isFinite(scale.max)) {
-            return 0;
-        }
-        // Guard against zero denominator
-        const denominator = scale.max - scale.min;
-        if (denominator === 0) {
-            return 0;
-        }
-        // Clamp score to scale bounds
-        const clampedScore = Math.max(scale.min, Math.min(scale.max, score));
-        const normalized = (clampedScore - scale.min) / denominator;
-        return Math.max(0, Math.min(1, normalized));
-    }
-    /**
-     * Convert normalized score back to scale
-     */
-    denormalizeScore(normalizedScore, scale = DEFAULT_SCORE_SCALE) {
-        const clamped = Math.max(0, Math.min(1, normalizedScore));
-        return scale.min + clamped * (scale.max - scale.min);
-    }
-    /**
-     * Check if score passes threshold
-     */
-    checkThreshold(normalizedScore) {
-        const threshold = this._config.threshold ?? 0.7;
-        return normalizedScore >= threshold;
-    }
-    /**
-     * Create a standardized score result
-     */
-    createScoreResult(score, reasoning, options = {}) {
-        const scale = options.scale ?? DEFAULT_SCORE_SCALE;
-        const safeScore = Number.isFinite(score) ? score : scale.min;
-        const clampedScore = Math.max(scale.min, Math.min(scale.max, safeScore));
-        const normalizedScore = this.normalizeScore(clampedScore, scale);
-        // Ensure no NaN leaks into published scores
-        const finalScore = Number.isFinite(clampedScore) ? clampedScore : 0;
-        const finalNormalized = Number.isFinite(normalizedScore)
-            ? normalizedScore
-            : 0;
-        return {
-            scorerId: this._metadata.id,
-            scorerName: this._metadata.name,
-            score: Number(finalScore.toFixed(scale.precision)),
-            normalizedScore: Number(finalNormalized.toFixed(4)),
-            scale,
-            reasoning,
-            passed: this.checkThreshold(finalNormalized),
-            threshold: this._config.threshold ?? 0.7,
-            confidence: options.confidence === undefined
-                ? undefined
-                : Number.isFinite(options.confidence)
-                    ? Math.max(0, Math.min(1, options.confidence))
-                    : 0,
-            metadata: options.metadata,
-            computeTime: 0, // Set by caller via executeWithTiming
-            error: options.error,
-        };
-    }
-    /**
-     * Create an error score result
-     */
-    createErrorResult(error) {
-        const errorMessage = error instanceof Error ? error.message : error;
-        return {
-            scorerId: this._metadata.id,
-            scorerName: this._metadata.name,
-            score: 0,
-            normalizedScore: 0,
-            scale: DEFAULT_SCORE_SCALE,
-            reasoning: `Scoring failed: ${errorMessage}`,
-            passed: false,
-            threshold: this._config.threshold ?? 0.7,
-            computeTime: 0,
-            error: errorMessage,
-        };
-    }
-    /**
-     * Execute scoring with timing and error handling
-     */
-    async executeWithTiming(scoringFn) {
-        const startTime = Date.now();
-        try {
-            const result = await scoringFn();
-            return {
-                ...result,
-                computeTime: Date.now() - startTime,
-            };
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            logger.error(`Scorer ${this._metadata.id} failed`, {
-                error: errorMessage,
-            });
-            return {
-                ...this.createErrorResult(errorMessage),
-                computeTime: Date.now() - startTime,
-            };
-        }
-    }
-    /**
-     * Execute scoring with timeout
-     */
-    async executeWithTimeout(fn, timeoutMs, operationName) {
-        return withTimeout(fn(), timeoutMs, ErrorFactory.evaluationTimeout(operationName, timeoutMs));
-    }
-    /**
-     * Execute with retry logic
-     */
-    async executeWithRetry(operation, retries) {
-        const maxRetries = retries ?? this._config.retries ?? 2;
-        let lastError;
-        for (let attempt = 0; attempt <= maxRetries; attempt++) {
-            try {
-                return await operation();
-            }
-            catch (error) {
-                lastError = error instanceof Error ? error : new Error(String(error));
-                if (attempt < maxRetries) {
-                    logger.debug(`Scorer ${this._metadata.id} retry ${attempt + 1}/${maxRetries}`, { error: lastError.message });
-                    // Exponential backoff
-                    await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 1000));
-                }
-            }
-        }
-        throw lastError ?? new Error("Operation failed after retries");
-    }
-}
-//# sourceMappingURL=baseScorer.js.map

package/dist/lib/evaluation/scorers/customScorerUtils.d.ts

@@ -1,86 +0,0 @@
-/**
- * @file Custom Scorer Utilities
- * Helper functions for creating custom scorers
- */
-import type { ScorerFunction, ScorerCategory, ScorerConfig, ScorerInput, ScorerMetadata, ScorerType } from "../../types/index.js";
-import { BaseScorer } from "./baseScorer.js";
-/**
- * Create scorer metadata with defaults
- */
-export declare function createScorerMetadata(id: string, name: string, options?: {
-    description?: string;
-    type?: ScorerType;
-    category?: ScorerCategory;
-    version?: string;
-    requiredInputs?: (keyof ScorerInput)[];
-    optionalInputs?: (keyof ScorerInput)[];
-    defaultConfig?: ScorerConfig;
-}): ScorerMetadata;
-/**
- * Create a simple function-based scorer
- */
-export declare function createFunctionScorer(id: string, name: string, scorerFn: ScorerFunction, options?: {
-    description?: string;
-    category?: ScorerCategory;
-    type?: ScorerType;
-    version?: string;
-    requiredInputs?: (keyof ScorerInput)[];
-    optionalInputs?: (keyof ScorerInput)[];
-    config?: ScorerConfig;
-}): BaseScorer;
-/**
- * Create a regex-based scorer
- */
-export declare function createRegexScorer(id: string, name: string, options: {
-    pattern: string | RegExp;
-    flags?: string;
-    shouldMatch?: boolean;
-    description?: string;
-    config?: ScorerConfig;
-}): BaseScorer;
-/**
- * Create a keyword presence scorer
- */
-export declare function createKeywordScorer(id: string, name: string, options: {
-    requiredKeywords?: string[];
-    forbiddenKeywords?: string[];
-    caseInsensitive?: boolean;
-    description?: string;
-    config?: ScorerConfig;
-}): BaseScorer;
-/**
- * Create a length-based scorer
- */
-export declare function createSimpleLengthScorer(id: string, name: string, options: {
-    minWords?: number;
-    maxWords?: number;
-    minChars?: number;
-    maxChars?: number;
-    description?: string;
-    config?: ScorerConfig;
-}): BaseScorer;
-/**
- * Compose multiple scorers into a single scorer with aggregation
- */
-export declare function composeScorers(id: string, name: string, scorers: BaseScorer[], options?: {
-    aggregation?: "average" | "min" | "max" | "weighted";
-    weights?: number[];
-    description?: string;
-    config?: ScorerConfig;
-}): BaseScorer;
-/**
- * Create a conditional scorer that only runs if a condition is met
- */
-export declare function createConditionalScorer(id: string, name: string, condition: (input: ScorerInput) => boolean, scorer: BaseScorer, options?: {
-    defaultScore?: number;
-    defaultReasoning?: string;
-    description?: string;
-    config?: ScorerConfig;
-}): BaseScorer;
-/**
- * Create a scorer that inverts the score (10 - score)
- */
-export declare function createInvertedScorer(id: string, name: string, scorer: BaseScorer, options?: {
-    description?: string;
-    config?: ScorerConfig;
-}): BaseScorer;

package/dist/lib/evaluation/scorers/customScorerUtils.js

@@ -1,382 +0,0 @@
-/**
- * @file Custom Scorer Utilities
- * Helper functions for creating custom scorers
- */
-import { BaseScorer, DEFAULT_SCORE_SCALE } from "./baseScorer.js";
-import { evaluationErrors } from "../errors/EvaluationError.js";
-/**
- * Create scorer metadata with defaults
- */
-export function createScorerMetadata(id, name, options) {
-    return {
-        id,
-        name,
-        description: options?.description ?? `Custom scorer: ${name}`,
-        type: options?.type ?? "rule",
-        category: options?.category ?? "custom",
-        version: options?.version ?? "1.0.0",
-        requiredInputs: options?.requiredInputs ?? ["response"],
-        optionalInputs: options?.optionalInputs ?? [
-            "query",
-            "context",
-            "groundTruth",
-        ],
-        defaultConfig: options?.defaultConfig ?? {
-            enabled: true,
-            threshold: 0.7,
-            weight: 1.0,
-            timeout: 5000,
-            retries: 0,
-        },
-    };
-}
-/**
- * Function-based scorer implementation
- */
-class FunctionScorer extends BaseScorer {
-    _scorerFn;
-    constructor(metadata, scorerFn, config) {
-        super(metadata, config);
-        this._scorerFn = scorerFn;
-    }
-    async score(input) {
-        return this.executeWithTiming(async () => {
-            // Validate input
-            const validation = this.validateInput(input);
-            if (!validation.valid) {
-                return this.createErrorResult(`Invalid input: ${validation.errors.join(", ")}`);
-            }
-            try {
-                const result = await this._scorerFn(input);
-                // Clamp score to valid range
-                const clampedScore = Math.max(DEFAULT_SCORE_SCALE.min, Math.min(DEFAULT_SCORE_SCALE.max, result.score));
-                return this.createScoreResult(clampedScore, result.reasoning, {
-                    metadata: result.metadata,
-                });
-            }
-            catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                return this.createErrorResult(errorMessage);
-            }
-        });
-    }
-}
-/**
- * Create a simple function-based scorer
- */
-export function createFunctionScorer(id, name, scorerFn, options) {
-    const metadata = createScorerMetadata(id, name, {
-        description: options?.description,
-        category: options?.category,
-        type: options?.type ?? "rule",
-        version: options?.version,
-        requiredInputs: options?.requiredInputs,
-        optionalInputs: options?.optionalInputs,
-    });
-    return new FunctionScorer(metadata, scorerFn, options?.config);
-}
-/**
- * Create a regex-based scorer
- */
-export function createRegexScorer(id, name, options) {
-    const metadata = createScorerMetadata(id, name, {
-        description: options.description ??
-            `Regex scorer checking for pattern: ${options.pattern}`,
-        type: "rule",
-        category: "quality",
-    });
-    let pattern;
-    if (typeof options.pattern === "string") {
-        if (options.pattern.length > 200) {
-            throw evaluationErrors.create("CONFIGURATION_ERROR", "Regex pattern exceeds maximum length of 200 characters", {
-                retryable: false,
-                details: { patternLength: options.pattern.length },
-            });
-        }
-        // Check for nested quantifiers that could cause catastrophic backtracking
-        if (/(\+|\*|\{)\S*(\+|\*|\{)/.test(options.pattern)) {
-            throw evaluationErrors.create("CONFIGURATION_ERROR", "Regex pattern contains nested quantifiers which may cause catastrophic backtracking", { retryable: false, details: { pattern: options.pattern } });
-        }
-        try {
-            pattern = new RegExp(options.pattern, options.flags ?? "i");
-        }
-        catch (e) {
-            throw evaluationErrors.create("CONFIGURATION_ERROR", `Invalid regex pattern: ${e instanceof Error ? e.message : String(e)}`, { retryable: false, cause: e instanceof Error ? e : undefined });
-        }
-    }
-    else {
-        // Validate precompiled RegExp with the same safety rules
-        const regexSource = options.pattern.source;
-        if (regexSource.length > 200) {
-            throw evaluationErrors.create("CONFIGURATION_ERROR", "Regex pattern exceeds maximum length of 200 characters", {
-                retryable: false,
-                details: { patternLength: regexSource.length },
-            });
-        }
-        if (/(\+|\*|\{)\S*(\+|\*|\{)/.test(regexSource)) {
-            throw evaluationErrors.create("CONFIGURATION_ERROR", "Regex pattern contains nested quantifiers which may cause catastrophic backtracking", { retryable: false, details: { pattern: regexSource } });
-        }
-        pattern = options.pattern;
-    }
-    const shouldMatch = options.shouldMatch ?? true;
-    return new FunctionScorer(metadata, async (input) => {
-        if (pattern.global) {
-            pattern.lastIndex = 0;
-        }
-        const matches = pattern.test(input.response);
-        const passed = shouldMatch ? matches : !matches;
-        return {
-            score: passed ? 10 : 0,
-            reasoning: passed
-                ? `Response ${shouldMatch ? "matches" : "does not match"} expected pattern`
-                : `Response ${shouldMatch ? "does not match" : "matches"} expected pattern`,
-            metadata: {
-                pattern: pattern.source,
-                flags: pattern.flags,
-                matches,
-                shouldMatch,
-            },
-        };
-    }, options.config);
-}
-/**
- * Create a keyword presence scorer
- */
-export function createKeywordScorer(id, name, options) {
-    const metadata = createScorerMetadata(id, name, {
-        description: options.description ?? `Keyword presence scorer`,
-        type: "rule",
-        category: "quality",
-    });
-    const requiredKeywords = options.requiredKeywords ?? [];
-    const forbiddenKeywords = options.forbiddenKeywords ?? [];
-    const caseInsensitive = options.caseInsensitive ?? true;
-    return new FunctionScorer(metadata, async (input) => {
-        const text = caseInsensitive
-            ? input.response.toLowerCase()
-            : input.response;
-        // Check required keywords
-        const foundRequired = [];
-        const missingRequired = [];
-        for (const keyword of requiredKeywords) {
-            const searchKeyword = caseInsensitive ? keyword.toLowerCase() : keyword;
-            if (text.includes(searchKeyword)) {
-                foundRequired.push(keyword);
-            }
-            else {
-                missingRequired.push(keyword);
-            }
-        }
-        // Check forbidden keywords
-        const foundForbidden = [];
-        for (const keyword of forbiddenKeywords) {
-            const searchKeyword = caseInsensitive ? keyword.toLowerCase() : keyword;
-            if (text.includes(searchKeyword)) {
-                foundForbidden.push(keyword);
-            }
-        }
-        // Calculate score
-        let score = 10;
-        const totalChecks = requiredKeywords.length + forbiddenKeywords.length;
-        if (totalChecks > 0) {
-            const passedChecks = foundRequired.length +
-                (forbiddenKeywords.length - foundForbidden.length);
-            score = (passedChecks / totalChecks) * 10;
-        }
-        // Generate reasoning
-        const reasons = [];
-        if (missingRequired.length > 0) {
-            reasons.push(`Missing required keywords: ${missingRequired.join(", ")}`);
-        }
-        if (foundForbidden.length > 0) {
-            reasons.push(`Found forbidden keywords: ${foundForbidden.join(", ")}`);
-        }
-        if (reasons.length === 0) {
-            reasons.push("All keyword requirements satisfied");
-        }
-        return {
-            score,
-            reasoning: reasons.join(". "),
-            metadata: {
-                foundRequired,
-                missingRequired,
-                foundForbidden,
-                totalRequired: requiredKeywords.length,
-                totalForbidden: forbiddenKeywords.length,
-            },
-        };
-    }, options.config);
-}
-/**
- * Create a length-based scorer
- */
-export function createSimpleLengthScorer(id, name, options) {
-    const metadata = createScorerMetadata(id, name, {
-        description: options.description ?? `Length scorer`,
-        type: "rule",
-        category: "quality",
-    });
-    return new FunctionScorer(metadata, async (input) => {
-        const wordCount = input.response
-            .trim()
-            .split(/\s+/)
-            .filter((w) => w.length > 0).length;
-        const charCount = input.response.length;
-        const issues = [];
-        let passed = true;
-        if (options.minWords !== undefined && wordCount < options.minWords) {
-            issues.push(`Too few words: ${wordCount} < ${options.minWords}`);
-            passed = false;
-        }
-        if (options.maxWords !== undefined && wordCount > options.maxWords) {
-            issues.push(`Too many words: ${wordCount} > ${options.maxWords}`);
-            passed = false;
-        }
-        if (options.minChars !== undefined && charCount < options.minChars) {
-            issues.push(`Too few characters: ${charCount} < ${options.minChars}`);
-            passed = false;
-        }
-        if (options.maxChars !== undefined && charCount > options.maxChars) {
-            issues.push(`Too many characters: ${charCount} > ${options.maxChars}`);
-            passed = false;
-        }
-        return {
-            score: passed ? 10 : 0,
-            reasoning: passed
-                ? `Length within bounds (${wordCount} words, ${charCount} chars)`
-                : issues.join("; "),
-            metadata: {
-                wordCount,
-                charCount,
-                minWords: options.minWords ?? null,
-                maxWords: options.maxWords ?? null,
-                minChars: options.minChars ?? null,
-                maxChars: options.maxChars ?? null,
-            },
-        };
-    }, options.config);
-}
-/**
- * Compose multiple scorers into a single scorer with aggregation
- */
-export function composeScorers(id, name, scorers, options) {
-    if (scorers.length === 0) {
-        throw new Error("composeScorers requires at least one scorer. An empty array would produce NaN/Infinity during aggregation.");
-    }
-    const metadata = createScorerMetadata(id, name, {
-        description: options?.description ??
-            `Composed scorer with ${scorers.length} sub-scorers`,
-        type: "hybrid",
-        category: "custom",
-    });
-    const aggregation = options?.aggregation ?? "average";
-    const weights = options?.weights ?? scorers.map(() => 1.0);
-    return new FunctionScorer(metadata, async (input) => {
-        // Run all scorers
-        const results = await Promise.all(scorers.map((scorer) => scorer.score(input)));
-        // Aggregate scores
-        let aggregatedScore;
-        switch (aggregation) {
-            case "min":
-                aggregatedScore = Math.min(...results.map((r) => r.score));
-                break;
-            case "max":
-                aggregatedScore = Math.max(...results.map((r) => r.score));
-                break;
-            case "weighted": {
-                let totalWeight = 0;
-                let weightedSum = 0;
-                for (let i = 0; i < results.length; i++) {
-                    const weight = weights[i] ?? 1.0;
-                    totalWeight += weight;
-                    weightedSum += results[i].score * weight;
-                }
-                aggregatedScore = totalWeight > 0 ? weightedSum / totalWeight : 0;
-                break;
-            }
-            case "average":
-            default:
-                aggregatedScore =
-                    results.reduce((sum, r) => sum + r.score, 0) / results.length;
-                break;
-        }
-        // Generate combined reasoning
-        const reasoning = results
-            .map((r, i) => `${scorers[i].metadata.name}: ${r.score.toFixed(1)}/10 - ${r.reasoning}`)
-            .join("; ");
-        return {
-            score: aggregatedScore,
-            reasoning: `Aggregated (${aggregation}): ${reasoning}`,
-            metadata: {
-                subScores: results.map((r, i) => ({
-                    scorerId: scorers[i].metadata.id,
-                    scorerName: scorers[i].metadata.name,
-                    score: r.score,
-                    passed: r.passed,
-                })),
-                aggregationMethod: aggregation,
-            },
-        };
-    }, options?.config);
-}
-/**
- * Create a conditional scorer that only runs if a condition is met
- */
-export function createConditionalScorer(id, name, condition, scorer, options) {
-    const metadata = createScorerMetadata(id, name, {
-        description: options?.description ??
-            `Conditional scorer wrapping ${scorer.metadata.name}`,
-        type: scorer.metadata.type,
-        category: scorer.metadata.category,
-    });
-    const defaultScore = options?.defaultScore ?? 10;
-    const defaultReasoning = options?.defaultReasoning ?? "Condition not met, using default score";
-    return new FunctionScorer(metadata, async (input) => {
-        if (condition(input)) {
-            const result = await scorer.score(input);
-            return {
-                score: result.score,
-                reasoning: result.reasoning,
-                metadata: {
-                    conditionMet: true,
-                    wrappedScorer: scorer.metadata.id,
-                    ...(result.metadata ?? {}),
-                },
-            };
-        }
-        return {
-            score: defaultScore,
-            reasoning: defaultReasoning,
-            metadata: {
-                conditionMet: false,
-                wrappedScorer: scorer.metadata.id,
-            },
-        };
-    }, options?.config);
-}
-/**
- * Create a scorer that inverts the score (10 - score)
- */
-export function createInvertedScorer(id, name, scorer, options) {
-    const metadata = createScorerMetadata(id, name, {
-        description: options?.description ??
-            `Inverted scorer wrapping ${scorer.metadata.name}`,
-        type: scorer.metadata.type,
-        category: scorer.metadata.category,
-    });
-    return new FunctionScorer(metadata, async (input) => {
-        const result = await scorer.score(input);
-        const invertedScore = DEFAULT_SCORE_SCALE.max - result.score;
-        return {
-            score: invertedScore,
-            reasoning: `Inverted: ${result.reasoning}`,
-            metadata: {
-                originalScore: result.score,
-                invertedScore,
-                wrappedScorer: scorer.metadata.id,
-                ...(result.metadata ?? {}),
-            },
-        };
-    }, options?.config);
-}
-//# sourceMappingURL=customScorerUtils.js.map