pi-ghost-autocomplete 0.3.1 → 0.3.2

package/dist/reranker.js

@@ -0,0 +1,324 @@
+/**
+ * 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.
+ */
+export const TIE_EPSILON = 1e-6;
+export const LENGTH_PRIOR_LOW = 5;
+export const LENGTH_PRIOR_HIGH = 30;
+export 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 const PREFIX_LENGTH_SCALE_THRESHOLD = 30;
+export const FALLBACK_MEDIAN_LENGTH = 15;
+export const MISSING_LOGPROB_NEUTRAL = 0.5;
+export const DEFAULT_WEIGHTS = {
+    logprob: 0.40,
+    profileBias: 0.25,
+    lengthPrior: 0.15,
+    agreement: 0.10,
+    editProximity: 0.10,
+};
+/**
+ * Merge candidates by exact text, accumulating sources and taking the max
+ * logprob across providers (agreement = positive evidence).
+ */
+export function mergeCandidates(cands) {
+    const map = new Map();
+    for (const c of cands) {
+        const existing = map.get(c.text);
+        if (existing) {
+            existing.sources.add(c.provider);
+            if (c.local)
+                existing.anyLocal = true;
+            if (c.avgLogprob !== undefined) {
+                if (existing.avgLogprob === undefined || c.avgLogprob > existing.avgLogprob) {
+                    existing.avgLogprob = c.avgLogprob;
+                }
+            }
+        }
+        else {
+            map.set(c.text, {
+                text: c.text,
+                avgLogprob: c.avgLogprob,
+                sources: new Set([c.provider]),
+                anyLocal: !!c.local,
+            });
+        }
+    }
+    return [...map.values()];
+}
+/**
+ * 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 function lengthPrior(len, prefixLen = 0) {
+    const bounds = lengthPriorBounds(prefixLen);
+    if (len <= 0 || len >= bounds.zeroAt)
+        return 0;
+    if (len >= LENGTH_PRIOR_LOW && len <= bounds.high)
+        return 1;
+    if (len < LENGTH_PRIOR_LOW)
+        return len / LENGTH_PRIOR_LOW;
+    // len between HIGH and ZERO_AT — linear decay
+    return (bounds.zeroAt - len) / (bounds.zeroAt - bounds.high);
+}
+/**
+ * Compute the prefix-length-aware HIGH and ZERO_AT bounds. Exposed for
+ * diagnostics + tests so the scaling logic can be verified directly.
+ */
+export function lengthPriorBounds(prefixLen) {
+    if (!Number.isFinite(prefixLen) || prefixLen <= PREFIX_LENGTH_SCALE_THRESHOLD) {
+        return { high: LENGTH_PRIOR_HIGH, zeroAt: LENGTH_PRIOR_ZERO_AT };
+    }
+    const scale = prefixLen / PREFIX_LENGTH_SCALE_THRESHOLD;
+    return {
+        high: LENGTH_PRIOR_HIGH * scale,
+        zeroAt: LENGTH_PRIOR_ZERO_AT * scale,
+    };
+}
+/**
+ * Min-max normalize `xs` into [0, 1]. If the spread is below `TIE_EPSILON`,
+ * every entry maps to 0.5 (neutral); this matches the spec's "missing
+ * logprob → 0.5" rule when applied to a uniform-logprob set.
+ */
+function minMaxNormalize(xs) {
+    if (xs.length === 0)
+        return [];
+    let min = Infinity;
+    let max = -Infinity;
+    for (const x of xs) {
+        if (x < min)
+            min = x;
+        if (x > max)
+            max = x;
+    }
+    const spread = max - min;
+    if (spread < TIE_EPSILON)
+        return xs.map(() => 0.5);
+    return xs.map((x) => (x - min) / spread);
+}
+export function rerank(cands, opts = {}) {
+    const w = opts.weights ?? DEFAULT_WEIGHTS;
+    const raceMembers = Math.max(1, opts.raceMembers ?? 1);
+    const profileBias = opts.profileBias ?? (() => 0);
+    // Track whether an editProximityScorer was supplied. Without one, the
+    // feature contributes nothing (raw zeros → uniform 0.5 after min-max
+    // would dilute all other signals by `w.editProximity` × 0.5). We
+    // short-circuit that by zeroing the editProximity term in the score
+    // sum when no signal is present.
+    const editProximityScorer = opts.editProximityScorer;
+    const median = opts.medianAcceptedLength ?? FALLBACK_MEDIAN_LENGTH;
+    const merged = mergeCandidates(cands);
+    if (merged.length === 0)
+        return [];
+    // Raw feature extraction.
+    const logprobs = merged.map((m) => m.avgLogprob === undefined ? Number.NaN : m.avgLogprob);
+    const profile = merged.map((m) => profileBias(m.text));
+    const editProx = editProximityScorer
+        ? merged.map((m) => editProximityScorer(m.text))
+        : merged.map(() => 0);
+    // `hasEditSignal` is true only when at least two raw values differ
+    // (so min-max norm produces useful ordering, not the uniform-0.5
+    // fallback). Single-candidate runs also count as no signal.
+    const editProxMin = editProx.length > 0 ? Math.min(...editProx) : 0;
+    const editProxMax = editProx.length > 0 ? Math.max(...editProx) : 0;
+    const hasEditSignal = editProxMax - editProxMin > TIE_EPSILON;
+    const prefixLen = opts.prefixLen ?? 0;
+    const lengths = merged.map((m) => lengthPrior(m.text.length, prefixLen));
+    const agreement = merged.map((m) => raceMembers > 1 ? (m.sources.size - 1) / (raceMembers - 1) : 0);
+    // Normalize each feature axis independently. For logprob, NaN slots get
+    // replaced with the neutral mid-value 0.5 after normalization.
+    const logprobsClean = logprobs.filter((x) => !Number.isNaN(x));
+    const normLp = logprobsClean.length > 0 ? minMaxNormalize(logprobsClean) : [];
+    let lpIdx = 0;
+    const logprobNorm = logprobs.map((x) => Number.isNaN(x) ? MISSING_LOGPROB_NEUTRAL : normLp[lpIdx++]);
+    const profileNorm = minMaxNormalize(profile);
+    const editProxNorm = minMaxNormalize(editProx);
+    const lengthNorm = minMaxNormalize(lengths);
+    // Agreement is already in [0, 1] — no normalization (PRD §M3c step 2).
+    const scored = merged.map((m, i) => {
+        const lp = logprobNorm[i];
+        const pb = profileNorm[i];
+        const lpr = lengthNorm[i];
+        const agr = agreement[i];
+        const ep = editProxNorm[i];
+        // `editProximity` may be undefined if the caller built RerankWeights
+        // via JSON / pre-#1 fixtures. Treat as 0 to preserve legacy behavior.
+        // When `hasEditSignal` is false (no scorer, or scorer produces a flat
+        // vector), min-max normalize would map every entry to the neutral
+        // 0.5, contributing a constant `w.editProximity * 0.5` to every
+        // score. Two harms: (1) dilutes effective contrast of all other
+        // signals; (2) shifts the score range below the calibrated
+        // `applyConfidenceGate` threshold. Fix: when dormant, zero this term
+        // AND scale the four other-feature weights up so the active weights
+        // sum back to the original total (preserves score range + threshold
+        // calibration).
+        //
+        // Caveat: the renormalization only restores the [0, 1] range when
+        // the other four weights summed to exactly `1 - editProximity`
+        // before scaling. Default `DEFAULT_WEIGHTS` and the parsed-env
+        // shapes satisfy this; arbitrary externally-supplied weights with
+        // a non-unit total may still shift the score range.
+        const wEp = w.editProximity ?? 0;
+        const inactive = !hasEditSignal && wEp > 0;
+        const scale = inactive ? 1 / Math.max(TIE_EPSILON, 1 - wEp) : 1;
+        const score = inactive
+            ? (w.logprob * lp + w.profileBias * pb + w.lengthPrior * lpr + w.agreement * agr) * scale
+            : w.logprob * lp + w.profileBias * pb + w.lengthPrior * lpr + w.agreement * agr + wEp * ep;
+        return {
+            text: m.text,
+            score,
+            avgLogprob: m.avgLogprob,
+            sources: [...m.sources].sort(),
+            scoreBreakdown: {
+                logprob: lp,
+                profileBias: pb,
+                lengthPrior: lpr,
+                agreement: agr,
+                editProximity: ep,
+            },
+        };
+    });
+    // Sort with tie-break chain.
+    scored.sort((a, b) => {
+        const ds = b.score - a.score;
+        if (Math.abs(ds) > TIE_EPSILON)
+            return ds;
+        // 1. Length closest to median.
+        const da = Math.abs(a.text.length - median);
+        const db = Math.abs(b.text.length - median);
+        if (da !== db)
+            return da - db;
+        // 2. Local provider preferred.
+        const aLocal = mergedHasLocal(merged, a.text);
+        const bLocal = mergedHasLocal(merged, b.text);
+        if (aLocal !== bLocal)
+            return aLocal ? -1 : 1;
+        // 3. Byte-compare (NOT localeCompare) for cross-machine determinism.
+        // localeCompare varies by locale and could change cycling order
+        // between Windows/Linux users on the same input.
+        if (a.text < b.text)
+            return -1;
+        if (a.text > b.text)
+            return 1;
+        return 0;
+    });
+    return scored;
+}
+function mergedHasLocal(merged, text) {
+    for (const m of merged)
+        if (m.text === text)
+            return m.anyLocal;
+    return false;
+}
+/** Default confidence gate threshold (PRD §M3c.1). Set to 0 to disable. */
+export const DEFAULT_MIN_CONFIDENCE = 0.55;
+/** Default top-vs-second margin gate (PRD §M3c.1). */
+export const DEFAULT_DISAGREEMENT_MARGIN = 0.05;
+/**
+ * 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 function applyConfidenceGate(ranked, opts = {}) {
+    if (ranked.length === 0)
+        return null;
+    const minConfidence = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+    const minMargin = opts.minMargin ?? DEFAULT_DISAGREEMENT_MARGIN;
+    const top = ranked[0];
+    if (top.score < minConfidence)
+        return null;
+    if (ranked.length >= 2) {
+        const second = ranked[1];
+        if (top.score - second.score < minMargin)
+            return null;
+    }
+    return top;
+}
+/**
+ * Parse `PI_GHOST_MIN_CONFIDENCE`. Returns fallback when unset, non-finite,
+ * or outside [0, 1].
+ */
+export function parseMinConfidenceEnv(raw) {
+    if (raw === undefined)
+        return DEFAULT_MIN_CONFIDENCE;
+    const v = Number(raw);
+    if (!Number.isFinite(v) || v < 0 || v > 1)
+        return DEFAULT_MIN_CONFIDENCE;
+    return v;
+}
+/**
+ * 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 function parseWeightsEnv(raw) {
+    if (!raw)
+        return DEFAULT_WEIGHTS;
+    const parts = raw.split(",").map((s) => Number(s.trim()));
+    if ((parts.length !== 4 && parts.length !== 5) || parts.some((n) => !Number.isFinite(n))) {
+        return DEFAULT_WEIGHTS;
+    }
+    const clamped = parts.map((n) => Math.max(0, n));
+    const [logprob, profileBias, lengthPrior, agreement, editProximity = 0] = clamped;
+    return {
+        logprob: logprob,
+        profileBias: profileBias,
+        lengthPrior: lengthPrior,
+        agreement: agreement,
+        editProximity,
+    };
+}
+//# sourceMappingURL=reranker.js.map

package/dist/reranker.js.map

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

package/dist/session-trie.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Session trie — fast-path completion source backed by the user's own past
+ * accepts and committed messages. See PRD §M2.
+ *
+ * Structurally this is `Map<prefix, Map<suffix, weight>>` rather than a true
+ * trie. At the PRD's 5000-entry cap, hash-lookup-by-exact-prefix is faster
+ * than walking a character trie, and the simpler shape is easier to reason
+ * about for decay and eviction.
+ *
+ * Insertion sources and weights (PRD §M2 "Insertion signals"):
+ *  - full accept: +3
+ *  - partial accept: +2 on the partial word, +1 on the full candidate
+ *  - committed user message: +1, prefix length 3..12 chars, suffix capped at
+ *    4 word-boundary shingles
+ *  - divergent dismiss: -0.5 (caller decides what counts as divergent;
+ *    per-keystroke dismisses must NOT call here, per PRD)
+ *
+ * Lookup gates (PRD §M2 "Lookup"):
+ *  - prefix length ≥ 3
+ *  - winner weight ≥ 1.5
+ *  - winner margin over runner-up ≥ 1.0
+ */
+export declare const MIN_PREFIX_LEN = 3;
+export declare const MIN_WEIGHT = 1.5;
+export declare const MIN_MARGIN = 1;
+export declare const DEFAULT_CAPACITY = 5000;
+export declare const DEFAULT_DECAY_EVERY = 200;
+export declare const DEFAULT_DECAY_FACTOR = 0.5;
+export declare const MAX_COMMITTED_PREFIX_LEN = 12;
+export declare const MAX_COMMITTED_SUFFIX_WORDS = 4;
+export interface TrieMatch {
+    ghost: string;
+    weight: number;
+    margin: number;
+}
+export interface TrieStats {
+    prefixes: number;
+    candidates: number;
+    insertsSinceDecay: number;
+}
+export declare class SessionTrie {
+    private readonly capacity;
+    private readonly decayEvery;
+    private readonly decayFactor;
+    /**
+     * `Map` insertion order is the LRU stamp — we re-insert a prefix key after
+     * touching it. Beyond capacity, the oldest key (first in iteration order)
+     * is evicted.
+     */
+    private readonly map;
+    private insertsSinceDecay;
+    constructor(capacity?: number, decayEvery?: number, decayFactor?: number);
+    get size(): number;
+    get stats(): TrieStats;
+    insert(prefix: string, suffix: string, weight: number): void;
+    /**
+     * Insert prefix→remainder pairs from an accepted ghost: prefix is the
+     * editor text immediately before the ghost; the full accepted suffix is
+     * the value. Weight is the caller's choice (+3 full, +2 partial-word, +1
+     * full-candidate-on-partial). Caller handles signal selection.
+     */
+    insertFromAccept(prefix: string, suffix: string, weight: number): void;
+    /**
+     * Insert sliding-window prefix→remainder pairs from a committed user
+     * message at weight +1 each (PRD §M2). Prefix lengths 3..12 chars,
+     * remainder capped at 4 word-boundary shingles to limit memory and avoid
+     * memorizing entire messages.
+     *
+     * Skips the whole message if any token matches a sensitive pattern.
+     */
+    insertFromCommittedMessage(text: string, weightPerShingle?: number): void;
+    /**
+     * Penalize an entry that diverged from the user's eventual commit.
+     * Per-keystroke dismisses must NOT call this (would penalize correct
+     * ghosts mid-typing). See PRD §M2.
+     */
+    penalize(prefix: string, suffix: string, magnitude?: number): void;
+    lookup(prefix: string): TrieMatch | null;
+    clear(): void;
+    /**
+     * Halve all weights. Exposed for testing; callers normally rely on the
+     * automatic decay every `decayEvery` inserts.
+     */
+    decayNow(): void;
+    private bumpCandidate;
+    private tickDecayCounter;
+    private enforceCapacity;
+}
+/**
+ * Return the end-of-word offsets in `text` (exclusive). For "ab cd ef", returns
+ * [2, 5, 8]. Used to align committed-message shingles to word boundaries.
+ */
+/**
+ * Pure helper used by `GhostEditor.onPromptCommitted`. Seeds `trie` from the
+ * committed text. If `accepted` is non-null AND the committed text contains
+ * the accepted ghost, the per-shingle weight drops from +1 to +0.25 to avoid
+ * double-counting (PRD §M2 "Insertion signals").
+ */
+export declare function seedTrieFromCommit(trie: SessionTrie, text: string, accepted: {
+    prefix: string;
+    ghost: string;
+} | null): void;
+//# sourceMappingURL=session-trie.d.ts.map

package/dist/session-trie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-trie.d.ts","sourceRoot":"","sources":["../src/session-trie.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,eAAO,MAAM,UAAU,IAAM,CAAC;AAC9B,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,oBAAoB,MAAM,CAAC;AACxC,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,WAAW;IAUtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAX7B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0C;IAC9D,OAAO,CAAC,iBAAiB,CAAK;gBAGZ,QAAQ,GAAE,MAAyB,EACnC,UAAU,GAAE,MAA4B,EACxC,WAAW,GAAE,MAA6B;IAO5D,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,SAAS,CAQrB;IAED,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ5D;;;;;OAKG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAItE;;;;;;;OAOG;IACH,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,SAAI,GAAG,IAAI;IAyBpE;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,IAAI;IAe/D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IA8CxC,KAAK,IAAI,IAAI;IAKb;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAehB,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,eAAe;CAOvB;AAED;;;GAGG;AACH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAChD,IAAI,CAIN"}