@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/search/ranker-rescore.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadActiveSearchRankerModel = loadActiveSearchRankerModel;
+exports.isSearchRankerEnabled = isSearchRankerEnabled;
+exports.rescoreSearchResults = rescoreSearchResults;
+exports.logisticScoreForRow = logisticScoreForRow;
+const ranker_features_js_1 = require("./ranker-features.js");
+const ranker_trainer_js_1 = require("./ranker-trainer.js");
+const question_type_js_1 = require("./question-type.js");
+function parseJsonObject(value) {
+    const parsed = JSON.parse(value);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('Expected JSON object');
+    }
+    return parsed;
+}
+function parseNumberArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((item) => (typeof item === 'number' && Number.isFinite(item) ? item : 0));
+}
+function parseQuestionWeights(value, fallback) {
+    const object = typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+    return {
+        correction: parseNumberArray(object.correction).length > 0
+            ? parseNumberArray(object.correction)
+            : [...fallback],
+        artifact: parseNumberArray(object.artifact).length > 0
+            ? parseNumberArray(object.artifact)
+            : [...fallback],
+        timeline: parseNumberArray(object.timeline).length > 0
+            ? parseNumberArray(object.timeline)
+            : [...fallback],
+        status: parseNumberArray(object.status).length > 0 ? parseNumberArray(object.status) : [...fallback],
+        decision_reason: parseNumberArray(object.decision_reason).length > 0
+            ? parseNumberArray(object.decision_reason)
+            : [...fallback],
+        how_to: parseNumberArray(object.how_to).length > 0 ? parseNumberArray(object.how_to) : [...fallback],
+        unknown: parseNumberArray(object.unknown).length > 0
+            ? parseNumberArray(object.unknown)
+            : [...fallback],
+    };
+}
+function modelFromRow(row) {
+    const payload = parseJsonObject(row.coefficients_json);
+    const coefficients = parseNumberArray(payload.coefficients);
+    const intercept = typeof payload.intercept === 'number' ? payload.intercept : 0;
+    const trainingRowsCount = typeof payload.training_rows_count === 'number' ? payload.training_rows_count : 0;
+    return {
+        model_id: row.model_id,
+        feature_set_version: row.feature_set_version,
+        trained_at: row.trained_at,
+        training_rows_count: trainingRowsCount,
+        coefficients,
+        intercept,
+        question_type_weights: parseQuestionWeights(payload.question_type_weights, coefficients),
+    };
+}
+function loadActiveRow(adapter) {
+    const row = adapter
+        .prepare(`
+        SELECT model_id, feature_set_version, coefficients_json, quality_gate_status, trained_at
+        FROM ranker_model_versions
+        WHERE active = 1
+        ORDER BY trained_at DESC
+        LIMIT 1
+      `)
+        .get();
+    return row ?? null;
+}
+function logSkipped(reason, modelId) {
+    console.warn(JSON.stringify({
+        event: 'search_ranker_skipped',
+        skipped_reason: reason,
+        model_id: modelId,
+        feature_set_version: ranker_features_js_1.SEARCH_RANKER_FEATURE_SET_VERSION,
+    }));
+}
+function loadActiveSearchRankerModel(adapter) {
+    const row = loadActiveRow(adapter);
+    if (!row) {
+        return null;
+    }
+    if (row.feature_set_version !== ranker_features_js_1.SEARCH_RANKER_FEATURE_SET_VERSION) {
+        logSkipped('feature_set_mismatch', row.model_id);
+        return null;
+    }
+    return modelFromRow(row);
+}
+function isSearchRankerEnabled(adapter) {
+    const row = adapter
+        .prepare(`
+        SELECT value_json
+        FROM search_ranker_settings
+        WHERE key = 'search_ranker_enabled'
+      `)
+        .get();
+    if (!row?.value_json) {
+        return true;
+    }
+    const parsed = JSON.parse(row.value_json);
+    return parsed !== false;
+}
+function baseScore(row) {
+    const candidates = [
+        row.final_score,
+        row.retrieval_score,
+        row.score,
+        row.similarity,
+        row.confidence,
+        row.case_rollup_score,
+        row.vector_score,
+        row.bm25_score,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+            return candidate;
+        }
+    }
+    return 0;
+}
+function resultId(row, fallback) {
+    const id = row.id ?? row.source_id ?? row.result_source_id;
+    return id === undefined || id === null ? String(fallback) : String(id);
+}
+function rescoreSearchResults(adapter, options) {
+    const passthrough = options.results;
+    if (options.useReranking) {
+        return {
+            results: passthrough,
+            model_id: null,
+            skipped_reason: 'llm_reranking_requested',
+        };
+    }
+    if (options.featureEnabled === false) {
+        return {
+            results: passthrough,
+            model_id: null,
+            skipped_reason: 'feature_disabled',
+        };
+    }
+    if (options.results.length < 2) {
+        return {
+            results: passthrough,
+            model_id: null,
+            skipped_reason: 'insufficient_result_count',
+        };
+    }
+    const row = loadActiveRow(adapter);
+    if (!row) {
+        return {
+            results: passthrough,
+            model_id: null,
+            skipped_reason: 'no_active_model',
+        };
+    }
+    if (row.feature_set_version !== ranker_features_js_1.SEARCH_RANKER_FEATURE_SET_VERSION) {
+        logSkipped('feature_set_mismatch', row.model_id);
+        return {
+            results: passthrough,
+            model_id: row.model_id,
+            skipped_reason: 'feature_set_mismatch',
+        };
+    }
+    if (row.quality_gate_status === 'failed') {
+        return {
+            results: passthrough,
+            model_id: row.model_id,
+            skipped_reason: 'quality_gate_failed',
+        };
+    }
+    if (row.quality_gate_status !== 'passed') {
+        return {
+            results: passthrough,
+            model_id: row.model_id,
+            skipped_reason: 'quality_gate_failed',
+        };
+    }
+    const model = modelFromRow(row);
+    const questionType = (0, question_type_js_1.classifyQuestionType)(options.query);
+    const scored = options.results.map((result, index) => {
+        const scoreBeforeRanker = baseScore(result);
+        const rankerScore = (0, ranker_trainer_js_1.scoreWithRankerModel)(model, result, options.query, questionType);
+        const finalScore = 0.8 * scoreBeforeRanker + 0.2 * rankerScore;
+        return {
+            result: {
+                ...result,
+                ranker_score: rankerScore,
+                score_before_ranker: scoreBeforeRanker,
+                final_score: finalScore,
+            },
+            index,
+            id: resultId(result, index),
+            finalScore,
+        };
+    });
+    scored.sort((left, right) => {
+        const diff = right.finalScore - left.finalScore;
+        if (Math.abs(diff) > 1e-12)
+            return diff;
+        if (left.index !== right.index)
+            return left.index - right.index;
+        return left.id.localeCompare(right.id);
+    });
+    return {
+        results: scored.map((entry) => entry.result),
+        model_id: model.model_id,
+    };
+}
+function logisticScoreForRow(model, row, query) {
+    const questionType = (0, question_type_js_1.classifyQuestionType)(query);
+    const features = (0, ranker_features_js_1.serializeFeatures)((0, ranker_features_js_1.extractFeatures)(row, query, { question_type: questionType }));
+    const coefficients = model.question_type_weights[questionType] ?? model.coefficients;
+    let score = model.intercept;
+    for (let index = 0; index < Math.min(coefficients.length, features.length); index += 1) {
+        score += coefficients[index] * features[index];
+    }
+    if (score >= 35)
+        return 1;
+    if (score <= -35)
+        return 0;
+    return 1 / (1 + Math.exp(-score));
+}
+//# sourceMappingURL=ranker-rescore.js.map

package/dist/search/ranker-trainer.d.ts

@@ -0,0 +1,94 @@
+import type { RunResult } from '../db-adapter/statement.js';
+import { featureSetVersion as currentFeatureSetVersion, SEARCH_RANKER_FEATURE_SET_VERSION } from './ranker-features.js';
+import { type QuestionType } from './question-type.js';
+export interface SearchRankerModel {
+    model_id: string;
+    feature_set_version: string;
+    trained_at: string;
+    training_rows_count: number;
+    coefficients: number[];
+    intercept: number;
+    question_type_weights: Record<QuestionType, number[]>;
+    training_window?: EffectiveTrainingWindow;
+}
+export interface RankerTrainerInput {
+    adapter: RankerTrainerAdapter;
+    since?: string;
+    until?: string;
+    minFeedbackRows?: number;
+    minDistinctQueries?: number;
+    featureSetVersion?: string;
+    now?: Date;
+}
+export interface EffectiveTrainingWindow {
+    since: string;
+    until: string;
+    retention_cutoff_at: string;
+    retention_days_at_train_time: number;
+    retention_warning: boolean;
+}
+export interface TrainOfflineRankerResult {
+    status: 'trained' | 'insufficient_data';
+    model?: SearchRankerModel;
+    effectiveWindow: EffectiveTrainingWindow;
+    counts: {
+        feedbackRows: number;
+        distinctQueries: number;
+    };
+}
+export interface BaselineMetrics {
+    ndcg: number;
+    mrr: number;
+    per_query: Record<string, {
+        ndcg: number;
+        mrr: number;
+    }>;
+}
+export interface RankerEvaluation {
+    bm25: BaselineMetrics;
+    vector: BaselineMetrics;
+    rrf: BaselineMetrics;
+    logistic: BaselineMetrics;
+    learned: BaselineMetrics;
+    passes: boolean;
+}
+export interface RankerTrainerAdapter {
+    prepare(sql: string): {
+        run(...params: unknown[]): RunResult;
+        get(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+    };
+    transaction?<T>(fn: () => T): T | (() => T);
+}
+interface QualityCandidate {
+    id: string;
+    source_type: string;
+    bm25_score: number;
+    vector_score: number;
+    case_rollup_score: number;
+    recency_score: number;
+    relevance: number;
+}
+interface QualityFixture {
+    query: string;
+    question_type: QuestionType;
+    candidates: QualityCandidate[];
+}
+export declare const RANKER_QUALITY_FIXTURES: readonly QualityFixture[];
+export declare function trainOfflineRanker(input: RankerTrainerInput): Promise<TrainOfflineRankerResult>;
+export declare function scoreWithRankerModel(model: SearchRankerModel, row: Record<string, unknown>, query: string, questionType: QuestionType): number;
+export declare function evaluateAgainstBaselines(_input: RankerTrainerInput, model: SearchRankerModel): Promise<RankerEvaluation>;
+export declare function insertRankerModelVersion(adapter: RankerTrainerAdapter, model: SearchRankerModel, evaluation: RankerEvaluation): Promise<{
+    model_id: string;
+    active: boolean;
+}>;
+export declare function activateRankerModel(adapter: RankerTrainerAdapter, model_id: string): Promise<'activated' | 'quality_gate_failed' | 'feature_set_mismatch' | 'not_found'>;
+export declare function ndcgAtK<T extends {
+    id: string;
+}>(results: readonly T[], relevanceMap: Map<string, number>, k: number): number;
+export declare function mrr<T extends {
+    id: string;
+}>(results: readonly T[], relevantSet: Set<string>): number;
+export declare function seedQualityFixtureFeedback(adapter: RankerTrainerAdapter, createdAt?: string): void;
+export { SEARCH_RANKER_FEATURE_SET_VERSION, currentFeatureSetVersion as featureSetVersion };
+//# sourceMappingURL=ranker-trainer.d.ts.map