pi-ghost-autocomplete 0.3.1 → 0.3.2

package/dist/replay.js

@@ -0,0 +1,225 @@
+/**
+ * Replay engine — pure functions. PRD §M5c.
+ *
+ * Given an `EvalExample` and a candidate continuation produced by a
+ * provider variant under test, compute per-example quality metrics. The
+ * caller drives the actual provider invocation (this module stays I/O-free
+ * so it's trivially unit-testable and deterministic for fixture providers).
+ */
+import { quantile } from "./bench.js";
+/**
+ * Score one replay. `exactMatch` is the strict equality test;
+ * `prefixMatchLen` is the longest common leading-character run between
+ * the actual and the expected continuation; `editDistance` is plain
+ * Levenshtein. `savedAt{1,3,5}` is the PRD's `chars-saved / max(1, L)`
+ * over the top-k candidates.
+ */
+export function evaluateExample(result) {
+    const expected = result.example.expected;
+    const actual = result.actual ?? "";
+    const exactMatch = actual === expected;
+    const prefixMatchLen = leadingMatch(actual, expected);
+    const editDistance = levenshtein(actual, expected);
+    const candidates = result.candidates ?? [actual];
+    return {
+        exactMatch,
+        prefixMatchLen,
+        editDistance,
+        savedAt1: savedAtK(candidates, expected, 1),
+        savedAt3: savedAtK(candidates, expected, 3),
+        savedAt5: savedAtK(candidates, expected, 5),
+        prefixRecallAt1: prefixRecallAtN(candidates, expected, 1),
+        prefixRecallAt3: prefixRecallAtN(candidates, expected, 3),
+        prefixRecallAt5: prefixRecallAtN(candidates, expected, 5),
+    };
+}
+/**
+ * First "identifier-or-punctuation" chunk of `s`. Mirrors the editor's
+ * `nextWordChunk` behavior without importing from ghost-editor (replay
+ * stays I/O-free). Skips leading whitespace, then either consumes an
+ * identifier run (`[A-Za-z0-9_]+`) or one punctuation char.
+ *
+ * Returns "" only when `s` has no non-whitespace content. The result
+ * INCLUDES the leading whitespace so that callers can `startsWith` the
+ * raw candidate against it without re-trimming.
+ */
+export function firstTokenPrefix(s) {
+    if (!s)
+        return "";
+    let i = 0;
+    while (i < s.length && /\s/.test(s[i] ?? ""))
+        i++;
+    if (i >= s.length)
+        return "";
+    const start = i;
+    const isIdent = /[A-Za-z0-9_]/.test(s[i] ?? "");
+    if (isIdent) {
+        while (i < s.length && /[A-Za-z0-9_]/.test(s[i] ?? ""))
+            i++;
+        return s.slice(0, i);
+    }
+    // Single punctuation char + leading ws.
+    return s.slice(0, start + 1);
+}
+/**
+ * 1 if any of `candidates[0..n)` starts with `firstTokenPrefix(expected)`,
+ * else 0. PRD §M5b extension — ChaI-TeA's per-token recall metric. The
+ * binary 0/1 shape (vs. fractional `saved@k`) makes the rate interpretable
+ * directly as "fraction of expected first-tokens recovered."
+ */
+export function prefixRecallAtN(candidates, expected, n) {
+    if (n <= 0 || candidates.length === 0 || !expected)
+        return 0;
+    const token = firstTokenPrefix(expected);
+    if (!token)
+        return 0;
+    const max = Math.min(n, candidates.length);
+    for (let i = 0; i < max; i++) {
+        const c = candidates[i] ?? "";
+        if (c.startsWith(token))
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Number of leading characters where `a` and `b` agree. Used as the
+ * `prefixMatchLen` quality metric (PRD §M5b).
+ */
+export function leadingMatch(a, b) {
+    const n = Math.min(a.length, b.length);
+    let i = 0;
+    while (i < n && a[i] === b[i])
+        i++;
+    return i;
+}
+/**
+ * `saved@k = max(0, charsSaved - acceptCost) / max(1, L)` per PRD §M5b,
+ * where `charsSaved` is the longest leading-match among ranks 1..k and
+ * `acceptCost = 1 + cycles` (one Right + cycle keystrokes). `k <= 0`
+ * returns 0; ranks beyond the array are skipped.
+ */
+export function savedAtK(candidates, expected, k) {
+    if (k <= 0)
+        return 0;
+    const L = Math.max(1, expected.length);
+    let bestSaved = 0;
+    let bestRank = 0;
+    const max = Math.min(k, candidates.length);
+    for (let i = 0; i < max; i++) {
+        const c = candidates[i] ?? "";
+        const saved = leadingMatch(c, expected);
+        if (saved > bestSaved) {
+            bestSaved = saved;
+            bestRank = i + 1;
+        }
+    }
+    const acceptCost = bestRank === 0 ? 0 : bestRank; // 1 Right + (rank-1) cycles
+    return Math.max(0, bestSaved - acceptCost) / L;
+}
+/**
+ * Classic Levenshtein distance with single-row DP. O(n*m) time, O(min)
+ * space. Used by replay to flag near-matches in the bench.
+ */
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    // Swap so `b` is shorter — smaller inner row.
+    if (a.length < b.length)
+        [a, b] = [b, a];
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, // deletion
+            curr[j - 1] + 1, // insertion
+            prev[j - 1] + cost);
+        }
+        const tmp = prev;
+        prev = curr;
+        curr = tmp;
+    }
+    return prev[b.length];
+}
+/**
+ * Aggregate per-example metrics + latencies into a single report. Skips
+ * error results from quality metrics but includes them in `count`/`errors`
+ * for transparency.
+ */
+export function summarizeReplay(results) {
+    if (results.length === 0) {
+        return zeroSummary();
+    }
+    const ok = results.filter((r) => !r.error);
+    const errors = results.length - ok.length;
+    if (ok.length === 0) {
+        return { ...zeroSummary(), count: results.length, errors };
+    }
+    let exact = 0;
+    let sumPrefix = 0;
+    let sumEdit = 0;
+    let sumS1 = 0;
+    let sumS3 = 0;
+    let sumS5 = 0;
+    let sumPR1 = 0;
+    let sumPR3 = 0;
+    let sumPR5 = 0;
+    for (const r of ok) {
+        const m = evaluateExample(r);
+        if (m.exactMatch)
+            exact++;
+        sumPrefix += m.prefixMatchLen;
+        sumEdit += m.editDistance;
+        sumS1 += m.savedAt1;
+        sumS3 += m.savedAt3;
+        sumS5 += m.savedAt5;
+        sumPR1 += m.prefixRecallAt1;
+        sumPR3 += m.prefixRecallAt3;
+        sumPR5 += m.prefixRecallAt5;
+    }
+    const latencies = ok.map((r) => r.latencyMs).sort((a, b) => a - b);
+    return {
+        count: results.length,
+        errors,
+        exactMatchRate: exact / ok.length,
+        meanPrefixMatchLen: sumPrefix / ok.length,
+        meanEditDistance: sumEdit / ok.length,
+        meanSavedAt1: sumS1 / ok.length,
+        meanSavedAt3: sumS3 / ok.length,
+        meanSavedAt5: sumS5 / ok.length,
+        prefixRecallAt1: sumPR1 / ok.length,
+        prefixRecallAt3: sumPR3 / ok.length,
+        prefixRecallAt5: sumPR5 / ok.length,
+        p50LatencyMs: quantile(latencies, 0.5),
+        p95LatencyMs: quantile(latencies, 0.95),
+    };
+}
+function zeroSummary() {
+    return {
+        count: 0,
+        errors: 0,
+        exactMatchRate: 0,
+        meanPrefixMatchLen: 0,
+        meanEditDistance: 0,
+        meanSavedAt1: 0,
+        meanSavedAt3: 0,
+        meanSavedAt5: 0,
+        prefixRecallAt1: 0,
+        prefixRecallAt3: 0,
+        prefixRecallAt5: 0,
+        p50LatencyMs: 0,
+        p95LatencyMs: 0,
+    };
+}
+// `quantile` re-exported from `bench.ts` so replay + bench reports use
+// the same percentile semantics (nearest-rank). Diverging implementations
+// would mean the same dataset reports different p95s in the two tools.
+export { quantile } from "./bench.js";
+//# sourceMappingURL=replay.js.map

package/dist/replay.js.map

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

package/dist/reranker.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Multi-source candidate reranker. See PRD §M3c.
+ *
+ * Pure function (`candidates, opts → ranked[]`). No I/O, no provider calls,
+ * no editor state — easy to unit-test without mocks.
+ *
+ * Pipeline:
+ *  1. Merge candidates by exact text (collapsing race-member duplicates,
+ *     taking the max logprob across sources and accumulating the source set).
+ *  2. Score each merged candidate as a weighted sum of normalized features:
+ *     logprob, profile-bias (M4 hook), length-prior, agreement bonus.
+ *  3. Tie-break (within 1e-6) on length-around-median, local-over-cloud,
+ *     lexicographic.
+ *
+ * Missing logprobs (Mercury FIM today) map to the neutral mid-value 0.5
+ * after normalization so a single-provider Mercury candidate isn't
+ * penalized against a multi-provider race that returns logprobs.
+ */
+import type { GhostCandidate } from "./providers/types.js";
+export declare const TIE_EPSILON = 0.000001;
+export declare const LENGTH_PRIOR_LOW = 5;
+export declare const LENGTH_PRIOR_HIGH = 30;
+export declare const LENGTH_PRIOR_ZERO_AT = 80;
+/**
+ * Prefix-length threshold above which the lengthPrior plateau and decay
+ * tail scale up. Empirically (ChaI-TeA + Copilot data): the longer the
+ * typed prefix, the longer the completion the user actually wants. Below
+ * this threshold the curve matches the original (prefix-blind) behavior.
+ */
+export declare const PREFIX_LENGTH_SCALE_THRESHOLD = 30;
+export declare const FALLBACK_MEDIAN_LENGTH = 15;
+export declare const MISSING_LOGPROB_NEUTRAL = 0.5;
+export interface RerankWeights {
+    logprob: number;
+    profileBias: number;
+    lengthPrior: number;
+    agreement: number;
+    /**
+     * Enhancement #1: weight on the edit-history proximity feature. Default
+     * 0.10. Set to 0 to disable. Trimmed from `logprob` (0.05) and
+     * `agreement` (0.05) so the weight sum remains 1.0.
+     */
+    editProximity: number;
+}
+export declare const DEFAULT_WEIGHTS: RerankWeights;
+export interface RerankerInput extends GhostCandidate {
+    /** Producing provider name. Multiple sources collapse on merge. */
+    provider: string;
+    /** True when `provider` is a `local` kind (Ollama / vLLM). */
+    local?: boolean;
+}
+export interface RerankerOpts {
+    weights?: RerankWeights;
+    /**
+     * Number of race members that participated. Used to normalize the
+     * agreement bonus: `(sources - 1) / (raceMembers - 1)`. Default 1.
+     */
+    raceMembers?: number;
+    /**
+     * Optional profile-bias scorer (M4 hook). Receives raw candidate text,
+     * returns a non-negative score. Missing → all candidates score 0.
+     */
+    profileBias?: (text: string) => number;
+    /**
+     * Enhancement #1: edit-history proximity scorer. Receives raw candidate
+     * text; returns a real number (negative permitted — candidates that
+     * resurrect recently-deleted tokens score below neutral). Missing →
+     * all candidates score 0.
+     */
+    editProximityScorer?: (text: string) => number;
+    /** Median length of historically-accepted ghosts. Default 15. */
+    medianAcceptedLength?: number;
+    /**
+     * Length of the typed prefix at the cursor (active line). When supplied
+     * the lengthPrior curve scales above `PREFIX_LENGTH_SCALE_THRESHOLD` so
+     * long-prefix queries are not penalized for long completions
+     * (empirical finding from ChaI-TeA / Copilot data).
+     */
+    prefixLen?: number;
+}
+export interface RerankedCandidate {
+    text: string;
+    score: number;
+    avgLogprob?: number;
+    sources: string[];
+    /** Internal — exposed for diagnostics + tie-break tests. */
+    scoreBreakdown: {
+        logprob: number;
+        profileBias: number;
+        lengthPrior: number;
+        agreement: number;
+        editProximity: number;
+    };
+}
+export interface MergedCandidate {
+    text: string;
+    avgLogprob?: number;
+    sources: Set<string>;
+    anyLocal: boolean;
+}
+/**
+ * Merge candidates by exact text, accumulating sources and taking the max
+ * logprob across providers (agreement = positive evidence).
+ */
+export declare function mergeCandidates(cands: RerankerInput[]): MergedCandidate[];
+/**
+ * Length prior for a candidate of `len` characters. `prefixLen` adjusts the
+ * plateau and decay bounds: completions get scored against a curve scaled to
+ * the typed prefix length, so long prefixes don't penalize long completions.
+ *
+ * When `prefixLen <= PREFIX_LENGTH_SCALE_THRESHOLD` (or omitted), the curve
+ * matches the original prefix-blind behavior: plateau over
+ * `[LENGTH_PRIOR_LOW, LENGTH_PRIOR_HIGH]`, linear ramp below LOW, linear
+ * decay between HIGH and `LENGTH_PRIOR_ZERO_AT`, and zero above ZERO_AT.
+ *
+ * When `prefixLen > PREFIX_LENGTH_SCALE_THRESHOLD`, the upper plateau (HIGH)
+ * and the zero-crossing (ZERO_AT) both scale by `prefixLen / THRESHOLD`:
+ *   - prefixLen = 30: scale = 1.0 → HIGH=30, ZERO_AT=80 (unchanged)
+ *   - prefixLen = 60: scale = 2.0 → HIGH=60, ZERO_AT=160
+ *   - prefixLen = 120: scale = 4.0 → HIGH=120, ZERO_AT=320
+ * LOW stays fixed — even very long prefixes still penalize trivially-short
+ * (1–4 char) completions, matching empirical user behavior.
+ */
+export declare function lengthPrior(len: number, prefixLen?: number): number;
+/**
+ * Compute the prefix-length-aware HIGH and ZERO_AT bounds. Exposed for
+ * diagnostics + tests so the scaling logic can be verified directly.
+ */
+export declare function lengthPriorBounds(prefixLen: number): {
+    high: number;
+    zeroAt: number;
+};
+export declare function rerank(cands: RerankerInput[], opts?: RerankerOpts): RerankedCandidate[];
+/** Default confidence gate threshold (PRD §M3c.1). Set to 0 to disable. */
+export declare const DEFAULT_MIN_CONFIDENCE = 0.55;
+/** Default top-vs-second margin gate (PRD §M3c.1). */
+export declare const DEFAULT_DISAGREEMENT_MARGIN = 0.05;
+export interface ConfidenceGateOpts {
+    /** Suppress the ghost when the top score is below this. Range [0, 1]. */
+    minConfidence?: number;
+    /** Suppress when top - 2nd margin is below this. */
+    minMargin?: number;
+}
+/**
+ * After rerank, decide whether to show the top candidate at all. Returns the
+ * top candidate when both gates pass, else `null` (caller should fall back to
+ * cache miss / no ghost). PRD §M3c.1.
+ *
+ * Both gates apply only to the top vs. second-best. With a single candidate,
+ * the margin gate trivially passes (no rival to disagree with) and only
+ * `minConfidence` matters.
+ *
+ * Score range: with default weights summing to 1.0 (PRD §M3c) and each
+ * feature normalized to [0, 1], the weighted sum lands in [0, 1] too —
+ * `minConfidence=0.55` and `minMargin=0.05` are calibrated against that
+ * range. User-supplied weights via `PI_GHOST_RERANK_WEIGHTS` that don't
+ * sum to 1.0 shift the effective score range; adjust gates accordingly
+ * or set them to 0 to disable.
+ *
+ * PRD §M3c.1 lists a third gate ("`avgLogprob` exists and falls below a
+ * calibrated provider-specific threshold"). It depends on accept-rate
+ * buckets from M5/M5c replay — deferred until that data is in hand.
+ * Setting `minConfidence=0` disables both implemented gates.
+ */
+export declare function applyConfidenceGate(ranked: RerankedCandidate[], opts?: ConfidenceGateOpts): RerankedCandidate | null;
+/**
+ * Parse `PI_GHOST_MIN_CONFIDENCE`. Returns fallback when unset, non-finite,
+ * or outside [0, 1].
+ */
+export declare function parseMinConfidenceEnv(raw: string | undefined): number;
+/**
+ * Parse `PI_GHOST_RERANK_WEIGHTS=a,b,c,d[,e]` into a `RerankWeights`.
+ * Accepts 4 or 5 comma-separated weights:
+ *   - 4 values: `logprob,profileBias,lengthPrior,agreement` (legacy form;
+ *     `editProximity` defaults to 0 to preserve pre-#1 behavior).
+ *   - 5 values: same plus `editProximity` (Enhancement #1).
+ * Falls back to defaults on parse error or invalid count. Negative weights
+ * are clamped to 0 ("ignore this signal").
+ */
+export declare function parseWeightsEnv(raw: string | undefined): RerankWeights;
+//# sourceMappingURL=reranker.d.ts.map

package/dist/reranker.d.ts.map

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