pi-ghost-autocomplete 0.11.0 → 0.12.0

package/dist/intent-classifier.d.ts

@@ -0,0 +1,90 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+import type { CompletionRegister } from "./intent.js";
+export interface IntentClassifierOptions {
+    /** Per-consult abort timeout. Default 400 ms (`PI_GHOST_INTENT_CLASSIFIER_TIMEOUT_MS`). */
+    timeoutMs: number;
+    /** Minimum answer confidence to apply a verdict. Default 0.6 (`PI_GHOST_INTENT_CLASSIFIER_MIN_CONFIDENCE`). */
+    minConfidence: number;
+    /** Verdict cache TTL. Default 60 s. */
+    ttlMs: number;
+    /** Verdict cache capacity (insertion-order eviction). Default 64. */
+    capacity: number;
+    /** Draft-prefix length the cache keys on. Default 32 chars. */
+    keyPrefixLen: number;
+    /**
+     * Debounce for the consult itself — a keystroke burst collapses into one
+     * classify call on the latest draft (the pending-set alone can't dedupe:
+     * every keystroke changes the cache key). Default 120 ms
+     * (`PI_GHOST_INTENT_CLASSIFIER_DEBOUNCE_MS`, clamped [0, 1000]).
+     */
+    consultDebounceMs: number;
+    now?: () => number;
+}
+/**
+ * Gate for consulting the classifier. Pure. True only when the heuristic
+ * marked the classification low-confidence AND the draft is long enough to
+ * classify meaningfully. Uses display width (string-width), matching the
+ * editor's completion gate — a 2-char CJK draft at the default `minChars=4`
+ * displays 4 columns wide, reaches the LLM, and must also be classifiable.
+ */
+export declare function shouldConsultClassifier(confidence: "high" | "low" | undefined, draft: string, minChars: number): boolean;
+/** Truncated, trimmed draft the verdict cache keys on. Exported for tests. */
+export declare function verdictCacheKey(draft: string, keyPrefixLen: number): string;
+/** The classification question handed to the classifier model. Pure. */
+export declare function buildClassifierContext(draft: string): unknown;
+/** Parse `PI_GHOST_INTENT_CLASSIFIER_TIMEOUT_MS` (clamped to [50, 5000]). */
+export declare function classifierTimeoutFromEnv(raw: string | undefined, fallback: number): number;
+/** Parse `PI_GHOST_INTENT_CLASSIFIER_MIN_CONFIDENCE` (clamped to [0, 1]). */
+export declare function classifierMinConfidenceFromEnv(raw: string | undefined, fallback: number): number;
+/** Parse `PI_GHOST_INTENT_CLASSIFIER_DEBOUNCE_MS` (clamped to [0, 1000]). */
+export declare function classifierConsultDebounceFromEnv(raw: string | undefined, fallback: number): number;
+export declare class IntentClassifier {
+    readonly spec: string;
+    private readonly registry;
+    private readonly opts;
+    private readonly classifyFn;
+    /** Resolved classifier model (any provider), or null when unresolvable. */
+    private modelPromise;
+    private readonly verdicts;
+    private readonly pending;
+    /** Consult debounce: keystroke bursts collapse into one classify call. */
+    private consultTimer;
+    private consultDraft;
+    private constructor();
+    /**
+     * Build from a config spec. Returns null when disabled (`off`/empty),
+     * when the host registry has no `classify` (pi < 0.99), or — for an
+     * explicit `provider/model-id` spec — when the typed lookup methods are
+     * absent. Model *resolution* stays lazy: `auto` needs the async
+     * `getAvailableOfType`, so an unavailable model degrades per-consult
+     * (no verdict) rather than disabling the feature at startup.
+     */
+    static create(spec: string, registry: unknown, opts?: Partial<IntentClassifierOptions>): IntentClassifier | null;
+    /** Resolve (once) the classifier model the spec names or auto-picks. */
+    private resolveModel;
+    private doResolveModel;
+    /**
+     * Fire-and-forget consult request. Rapid calls (one per keystroke)
+     * collapse into a single classify on the latest draft after
+     * {@link IntentClassifierOptions.consultDebounceMs} of quiet — the
+     * pending-set alone cannot dedupe because every keystroke changes the
+     * cache key. Never blocks, never throws.
+     */
+    maybeConsult(draft: string): void;
+    private fireConsult;
+    private storeVerdict;
+    /**
+     * Fresh verdict for the draft's cache key, or null. Prefix-aware: a
+     * verdict consulted on an earlier prefix of the same line applies as
+     * the line grows (and, symmetrically, after backspacing into it), so
+     * the classification of a line's opening sticks without re-consulting
+     * per keystroke. Strong-classification gating in the editor bounds any
+     * stale-prefix reuse.
+     */
+    verdictFor(draft: string): CompletionRegister | null;
+    /** Number of live verdicts — surfaced in `/ghost` diagnostics. */
+    get verdictCount(): number;
+}

package/dist/intent.d.ts

@@ -221,6 +221,18 @@ export interface IntentClassification {
     intent: PromptIntent;
     register: CompletionRegister;
     proseReason?: ProseReason;
+    /**
+     * Heuristic signal strength (track C). `"low"` marks the two weak spots
+     * of the regex pipeline — single-line prose (persona split between
+     * `general-prose` and `agent-message` is guesswork below 4 lines of
+     * context) and the final fallback `instruction` (no verb, marker, or
+     * question shape matched — the draft could equally be code like
+     * `npm install`). The editor consults the optional intent classifier
+     * (pi ≥ 0.99 `registry.classify`, e.g. Jev or a llama.cpp classifier)
+     * only for `"low"` classifications, so strong signals never pay the
+     * round-trip. Absent means `"high"` (pre-track-C callers).
+     */
+    confidence?: "high" | "low";
 }
 /**
  * Detailed variant of `classifyPromptIntent`. Same classification order,