@jaepil/uqa 0.1.0

package/dist/types/src/scoring/external-prior.d.ts

@@ -0,0 +1,55 @@
+import type { IndexStats } from "../core/types.js";
+import type { BayesianBM25Params } from "./bayesian-bm25.js";
+/**
+ * A prior function that maps document fields to a probability in (0, 1).
+ * Returns 0.5 (neutral prior) when no prior information is available.
+ */
+export type PriorFn = (docFields: Record<string, unknown>) => number;
+/**
+ * Bayesian BM25 scorer with external prior.
+ *
+ * Computes the BM25 likelihood probability, then combines it with
+ * an external prior via log-odds addition to produce a posterior.
+ */
+export declare class ExternalPriorScorer {
+    private readonly _bm25;
+    private readonly _transform;
+    private readonly _priorFn;
+    constructor(params: BayesianBM25Params, indexStats: IndexStats, priorFn: PriorFn);
+    /**
+     * Compute posterior with external prior via log-odds fusion.
+     *
+     * 1. Compute BM25 raw score.
+     * 2. Convert to likelihood probability via BayesianProbabilityTransform.
+     * 3. Compute prior from document fields.
+     * 4. Combine via log-odds addition: logit(posterior) = logit(likelihood) + logit(prior).
+     * 5. Convert back to probability via sigmoid.
+     */
+    scoreWithPrior(termFreq: number, docLength: number, docFreq: number, docFields: Record<string, unknown>): number;
+}
+/**
+ * Create a recency-based prior function.
+ *
+ * Documents with a more recent timestamp in the given field receive higher
+ * prior probability. The prior decays exponentially with age:
+ *
+ *     prior = 0.5 + 0.4 * exp(-age_days / decay_days)
+ *
+ * Returns 0.5 (neutral prior) when the field is missing or unparseable.
+ *
+ * @param field - The document field containing a date/timestamp.
+ * @param decayDays - Half-life in days for the exponential decay.
+ */
+export declare function recencyPrior(field: string, decayDays?: number): PriorFn;
+/**
+ * Create an authority-based prior function.
+ *
+ * Maps categorical authority levels to prior probabilities.
+ * Default levels: {"high": 0.8, "medium": 0.6, "low": 0.4}.
+ * Returns 0.5 (neutral) when the field is missing or unrecognized.
+ *
+ * @param field - The document field containing the authority level.
+ * @param levels - Mapping from level name to prior probability.
+ */
+export declare function authorityPrior(field: string, levels?: Record<string, number> | null): PriorFn;
+//# sourceMappingURL=external-prior.d.ts.map

package/dist/types/src/scoring/external-prior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-prior.d.ts","sourceRoot":"","sources":["../../../../src/scoring/external-prior.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAuB7D;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;AAErE;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;gBAEvB,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO;IAUhF;;;;;;;;OAQG;IACH,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,MAAM;CAoBV;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAkBrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,GACrC,OAAO,CAQT"}

package/dist/types/src/scoring/fusion-wand.d.ts

@@ -0,0 +1,19 @@
+import { PostingList } from "../core/posting-list.js";
+import { BoundTightnessAnalyzer } from "./wand.js";
+export declare class FusionWANDScorer {
+    protected readonly _signalPostingLists: PostingList[];
+    protected readonly _signalUpperBounds: number[];
+    protected readonly _alpha: number;
+    protected readonly _k: number;
+    protected readonly _gating: string | null;
+    constructor(signalPostingLists: PostingList[], signalUpperBounds: number[], alpha?: number, k?: number, gating?: string | null);
+    private _computeFusedUpperBound;
+    scoreTopK(): PostingList;
+}
+export declare class TightenedFusionWANDScorer extends FusionWANDScorer {
+    readonly _tighteningFactor: number;
+    readonly _originalBounds: number[];
+    readonly boundAnalyzer: BoundTightnessAnalyzer;
+    constructor(signalPostingLists: PostingList[], signalUpperBounds: number[], alpha?: number, k?: number, gating?: string | null, tighteningFactor?: number);
+}
+//# sourceMappingURL=fusion-wand.d.ts.map

package/dist/types/src/scoring/fusion-wand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion-wand.d.ts","sourceRoot":"","sources":["../../../../src/scoring/fusion-wand.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAoBnD,qBAAa,gBAAgB;IAC3B,SAAS,CAAC,QAAQ,CAAC,mBAAmB,EAAE,WAAW,EAAE,CAAC;IACtD,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAChD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAC9B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;gBAGxC,kBAAkB,EAAE,WAAW,EAAE,EACjC,iBAAiB,EAAE,MAAM,EAAE,EAC3B,KAAK,SAAM,EACX,CAAC,SAAK,EACN,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IASxB,OAAO,CAAC,uBAAuB;IAS/B,SAAS,IAAI,WAAW;CAmEzB;AAID,qBAAa,yBAA0B,SAAQ,gBAAgB;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,sBAAsB,CAAC;gBAG7C,kBAAkB,EAAE,WAAW,EAAE,EACjC,iBAAiB,EAAE,MAAM,EAAE,EAC3B,KAAK,SAAM,EACX,CAAC,SAAK,EACN,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EACtB,gBAAgB,SAAM;CAQzB"}

package/dist/types/src/scoring/multi-field.d.ts

@@ -0,0 +1,10 @@
+import type { IndexStats } from "../core/types.js";
+import type { BayesianBM25Params } from "./bayesian-bm25.js";
+export declare class MultiFieldBayesianScorer {
+    private readonly _fieldNames;
+    private readonly _scorers;
+    private readonly _weights;
+    constructor(fieldConfigs: [string, BayesianBM25Params, number][], indexStats: IndexStats);
+    scoreDocument(_docId: number, termFreqPerField: Record<string, number>, docLengthPerField: Record<string, number>, docFreqPerField: Record<string, number>): number;
+}
+//# sourceMappingURL=multi-field.d.ts.map

package/dist/types/src/scoring/multi-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-field.d.ts","sourceRoot":"","sources":["../../../../src/scoring/multi-field.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;gBAGlC,YAAY,EAAE,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,EACpD,UAAU,EAAE,UAAU;IAYxB,aAAa,CACX,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtC,MAAM;CA2BV"}

package/dist/types/src/scoring/parameter-learner.d.ts

@@ -0,0 +1,42 @@
+import type { FitOptions, UpdateOptions } from "bayesian-bm25";
+/**
+ * Online parameter learning for Bayesian BM25.
+ *
+ * Wraps BayesianProbabilityTransform.fit() and .update() to learn
+ * calibration parameters (alpha, beta, baseRate) from relevance
+ * judgments. Supports both batch learning (fit) and incremental
+ * online updates (update).
+ */
+export declare class ParameterLearner {
+    private readonly _transform;
+    /**
+     * @param alpha - Initial scaling exponent (default 1.0).
+     * @param beta - Initial offset (default 0.0).
+     * @param baseRate - Prior base rate of relevance (default 0.5).
+     */
+    constructor(alpha?: number, beta?: number, baseRate?: number);
+    /**
+     * Batch-learn calibration parameters from scored documents.
+     *
+     * @param scores - Array of raw BM25 scores.
+     * @param labels - Array of binary relevance labels (0 or 1).
+     * @param options - Optional fit options (mode, tfs, doc_len_ratios).
+     * @returns The learned parameters as a dict with keys: alpha, beta, baseRate.
+     */
+    fit(scores: number[], labels: number[], options?: FitOptions): Record<string, number>;
+    /**
+     * Online update with a single observation.
+     *
+     * @param score - A single raw BM25 score.
+     * @param label - Binary relevance label (0 or 1).
+     * @param options - Optional update options (learning_rate, tf, doc_len_ratio).
+     */
+    update(score: number, label: number, options?: UpdateOptions): void;
+    /**
+     * Return current learned parameters.
+     *
+     * @returns Dict with keys: alpha, beta, baseRate.
+     */
+    params(): Record<string, number>;
+}
+//# sourceMappingURL=parameter-learner.d.ts.map

package/dist/types/src/scoring/parameter-learner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameter-learner.d.ts","sourceRoot":"","sources":["../../../../src/scoring/parameter-learner.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE/D;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAE1D;;;;OAIG;gBACS,KAAK,SAAM,EAAE,IAAI,SAAM,EAAE,QAAQ,SAAM;IAQnD;;;;;;;OAOG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,CAAC,EAAE,UAAU,GACnB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAKzB;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI;IAInE;;;;OAIG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAOjC"}

package/dist/types/src/scoring/vector.d.ts

@@ -0,0 +1,42 @@
+import type { VectorProbabilityTransform } from "bayesian-bm25";
+/**
+ * Vector similarity to probability conversion.
+ *
+ * Provides both uncalibrated and calibrated modes for converting
+ * cosine similarity scores into relevance probabilities.
+ */
+export declare class VectorScorer {
+    /**
+     * Compute cosine similarity between two vectors.
+     *
+     * Returns 0.0 if either vector has zero norm.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns Cosine similarity in [-1, 1].
+     */
+    static cosineSimilarity(a: Float64Array, b: Float64Array): number;
+    /**
+     * Definition 7.1.2: P_vector = (1 + score) / 2 (uncalibrated).
+     *
+     * Converts a cosine similarity in [-1, 1] to a probability in [0, 1]
+     * using the simple linear mapping.
+     *
+     * @param cosineSim - Cosine similarity value.
+     * @returns Probability in [0, 1].
+     */
+    static similarityToProbability(cosineSim: number): number;
+    /**
+     * Likelihood ratio calibration (Theorem 3.1.1, Paper 5).
+     *
+     * Converts cosine similarities to calibrated probabilities using a
+     * pre-configured VectorProbabilityTransform with background distribution.
+     *
+     * @param similarities - Cosine similarities in [-1, 1] for the top-K results.
+     * @param calibrator - Pre-configured calibrator with background distribution.
+     * @param weights - External relevance weights. If null, uniform weights.
+     * @returns Calibrated probabilities in (0, 1).
+     */
+    static calibratedProbabilities(similarities: number[], calibrator: VectorProbabilityTransform, weights?: number[] | null): number[];
+}
+//# sourceMappingURL=vector.d.ts.map

package/dist/types/src/scoring/vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../../../../src/scoring/vector.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAGhE;;;;;GAKG;AAEH,qBAAa,YAAY;IACvB;;;;;;;;OAQG;IACH,MAAM,CAAC,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM;IAIjE;;;;;;;;OAQG;IACH,MAAM,CAAC,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIzD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,uBAAuB,CAC5B,YAAY,EAAE,MAAM,EAAE,EACtB,UAAU,EAAE,0BAA0B,EACtC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GACxB,MAAM,EAAE;CAQZ"}

package/dist/types/src/scoring/wand.d.ts

@@ -0,0 +1,51 @@
+import { PostingList } from "../core/posting-list.js";
+import type { InvertedIndex } from "../storage/abc/inverted-index.js";
+export interface WANDScorerLike {
+    score(termFreq: number, docLength: number, docFreq: number): number;
+    upperBound(docFreq: number): number;
+}
+export declare class WANDScorer {
+    protected readonly _scorers: WANDScorerLike[];
+    protected readonly _k: number;
+    protected readonly _postingLists: PostingList[];
+    protected readonly _invertedIndex: InvertedIndex | null;
+    protected readonly _fields: string[];
+    protected readonly _terms: string[];
+    protected readonly _upperBounds: number[];
+    private readonly _entries;
+    private readonly _cursors;
+    constructor(scorers: WANDScorerLike[], k: number, postingLists: PostingList[], invertedIndex?: InvertedIndex | null, fields?: string[] | null, terms?: string[] | null);
+    protected _computeUpperBounds(): number[];
+    scoreTopK(): PostingList;
+}
+export declare class BlockMaxWANDScorer {
+    private readonly _scorers;
+    private readonly _k;
+    private readonly _blockMaxIndex;
+    private readonly _postingLists;
+    private readonly _invertedIndex;
+    private readonly _fields;
+    private readonly _terms;
+    private readonly _blockSize;
+    private readonly _tableName;
+    constructor(scorers: WANDScorerLike[], k: number, blockMaxIndex: {
+        getBlockMax(field: string, term: string, blockIdx: number, tableName?: string): number;
+    }, postingLists: PostingList[], invertedIndex?: InvertedIndex | null, fields?: string[] | null, terms?: string[] | null, blockSize?: number, tableName?: string);
+    private _getBlockIdx;
+    scoreTopK(): PostingList;
+}
+export declare class BoundTightnessAnalyzer {
+    private _data;
+    record(upperBound: number, actualMax: number): void;
+    tightnessRatio(): number;
+    slack(): number;
+    worstBoundIndex(): number;
+    clear(): void;
+}
+export declare class AdaptiveWANDScorer extends WANDScorer {
+    private readonly _tighteningFactor;
+    readonly _analyzer: BoundTightnessAnalyzer;
+    constructor(scorers: WANDScorerLike[], k: number, postingLists: PostingList[], invertedIndex?: InvertedIndex | null, fields?: string[] | null, terms?: string[] | null, tighteningFactor?: number);
+    protected _computeUpperBounds(): number[];
+}
+//# sourceMappingURL=wand.d.ts.map

package/dist/types/src/scoring/wand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wand.d.ts","sourceRoot":"","sources":["../../../../src/scoring/wand.ts"],"names":[],"mappings":"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"}