@seanhogg/builderforce-memory 2026.6.18

package/dist/cache/FetchSemanticCacheBackend.d.ts

@@ -0,0 +1,40 @@
+/**
+ * FetchSemanticCacheBackend – the shared (L2) tier of the SemanticCache, backed
+ * by the BuilderForce.ai gateway's vector store over HTTP.
+ *
+ * One client used by both consumers (browser + agent) so a semantic hit on one
+ * surface is reusable by the other. Pure `fetch` — no environment-specific deps;
+ * inject `fetchImpl` in tests.
+ *
+ * Wire protocol (gateway `/v1/semantic-cache`):
+ *   POST /lookup  { embedding: number[], threshold, namespace? } → { hit?: { response, score } }
+ *   POST /store   { embedding: number[], response, namespace?, meta? } → 2xx
+ */
+import type { SemanticCacheBackend } from './SemanticCache.js';
+export interface FetchSemanticCacheBackendOptions {
+    /** Gateway base URL, e.g. 'https://api.builderforce.ai'. Trailing slash trimmed. */
+    baseUrl: string;
+    /** Tenant API key (sent as a bearer token). */
+    apiKey: string;
+    /**
+     * Optional cache partition. Scope hits to a tenant/model/agent so unrelated
+     * traffic can't cross-hit. Defaults to the gateway's per-tenant default.
+     */
+    namespace?: string;
+    /** Injectable fetch (defaults to global fetch). */
+    fetchImpl?: typeof fetch;
+}
+export declare class FetchSemanticCacheBackend implements SemanticCacheBackend {
+    private readonly _base;
+    private readonly _apiKey;
+    private readonly _namespace;
+    private readonly _fetch;
+    constructor(opts: FetchSemanticCacheBackendOptions);
+    lookup(embedding: Float32Array, threshold: number): Promise<{
+        response: string;
+        score: number;
+    } | undefined>;
+    store(embedding: Float32Array, response: string, meta?: Record<string, unknown>): Promise<void>;
+    private _headers;
+}
+//# sourceMappingURL=FetchSemanticCacheBackend.d.ts.map

package/dist/cache/FetchSemanticCacheBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FetchSemanticCacheBackend.d.ts","sourceRoot":"","sources":["../../src/cache/FetchSemanticCacheBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,WAAW,gCAAgC;IAC7C,oFAAoF;IACpF,OAAO,EAAI,MAAM,CAAC;IAClB,+CAA+C;IAC/C,MAAM,EAAK,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAG,MAAM,CAAC;IACpB,mDAAmD;IACnD,SAAS,CAAC,EAAG,OAAO,KAAK,CAAC;CAC7B;AAED,qBAAa,yBAA0B,YAAW,oBAAoB;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAE/B,IAAI,EAAE,gCAAgC;IAO5C,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAiB5G,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAarG,OAAO,CAAC,QAAQ;CAMnB"}

package/dist/cache/FetchSemanticCacheBackend.js

@@ -0,0 +1,61 @@
+/**
+ * FetchSemanticCacheBackend – the shared (L2) tier of the SemanticCache, backed
+ * by the BuilderForce.ai gateway's vector store over HTTP.
+ *
+ * One client used by both consumers (browser + agent) so a semantic hit on one
+ * surface is reusable by the other. Pure `fetch` — no environment-specific deps;
+ * inject `fetchImpl` in tests.
+ *
+ * Wire protocol (gateway `/v1/semantic-cache`):
+ *   POST /lookup  { embedding: number[], threshold, namespace? } → { hit?: { response, score } }
+ *   POST /store   { embedding: number[], response, namespace?, meta? } → 2xx
+ */
+export class FetchSemanticCacheBackend {
+    _base;
+    _apiKey;
+    _namespace;
+    _fetch;
+    constructor(opts) {
+        this._base = opts.baseUrl.replace(/\/$/, '');
+        this._apiKey = opts.apiKey;
+        this._namespace = opts.namespace;
+        this._fetch = opts.fetchImpl ?? fetch;
+    }
+    async lookup(embedding, threshold) {
+        const res = await this._fetch(`${this._base}/v1/semantic-cache/lookup`, {
+            method: 'POST',
+            headers: this._headers(),
+            body: JSON.stringify({
+                embedding: Array.from(embedding),
+                threshold,
+                ...(this._namespace ? { namespace: this._namespace } : {}),
+            }),
+        });
+        if (!res.ok)
+            return undefined;
+        const json = await res.json().catch(() => null);
+        const hit = json?.hit;
+        if (!hit || typeof hit.response !== 'string' || typeof hit.score !== 'number')
+            return undefined;
+        return { response: hit.response, score: hit.score };
+    }
+    async store(embedding, response, meta) {
+        await this._fetch(`${this._base}/v1/semantic-cache/store`, {
+            method: 'POST',
+            headers: this._headers(),
+            body: JSON.stringify({
+                embedding: Array.from(embedding),
+                response,
+                ...(this._namespace ? { namespace: this._namespace } : {}),
+                ...(meta ? { meta } : {}),
+            }),
+        });
+    }
+    _headers() {
+        return {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this._apiKey}`,
+        };
+    }
+}
+//# sourceMappingURL=FetchSemanticCacheBackend.js.map

package/dist/cache/FetchSemanticCacheBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FetchSemanticCacheBackend.js","sourceRoot":"","sources":["../../src/cache/FetchSemanticCacheBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkBH,MAAM,OAAO,yBAAyB;IACjB,KAAK,CAAe;IACpB,OAAO,CAAa;IACpB,UAAU,CAAsB;IAChC,MAAM,CAAoB;IAE3C,YAAY,IAAsC;QAC9C,IAAI,CAAC,KAAK,GAAQ,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,GAAM,IAAI,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,MAAM,GAAO,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,SAAuB,EAAE,SAAiB;QACnD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,2BAA2B,EAAE;YACpE,MAAM,EAAG,MAAM;YACf,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE;YACxB,IAAI,EAAK,IAAI,CAAC,SAAS,CAAC;gBACpB,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;gBAChC,SAAS;gBACT,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7D,CAAC;SACL,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,SAAS,CAAC;QAC9B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAA6D,CAAC;QAC5G,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,CAAC;QACtB,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAChG,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,SAAuB,EAAE,QAAgB,EAAE,IAA8B;QACjF,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,0BAA0B,EAAE;YACvD,MAAM,EAAG,MAAM;YACf,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE;YACxB,IAAI,EAAK,IAAI,CAAC,SAAS,CAAC;gBACpB,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;gBAChC,QAAQ;gBACR,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1D,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC5B,CAAC;SACL,CAAC,CAAC;IACP,CAAC;IAEO,QAAQ;QACZ,OAAO;YACH,cAAc,EAAG,kBAAkB;YACnC,aAAa,EAAI,UAAU,IAAI,CAAC,OAAO,EAAE;SAC5C,CAAC;IACN,CAAC;CACJ"}

package/dist/cache/SemanticCache.d.ts

@@ -0,0 +1,105 @@
+/**
+ * SemanticCache – an embedding-keyed read-through cache for LLM completions.
+ *
+ * Unlike the exact-match ResponseCache (which keys on the byte-identical prompt),
+ * this keys on the *meaning* of the query: it embeds the query and serves a
+ * cached answer when a stored entry is within `threshold` cosine similarity.
+ * That catches paraphrases — "fix the auth bug" ≈ "login is broken" — which is
+ * where real frontier-call avoidance (and token savings) comes from.
+ *
+ * Two tiers, mirroring the project's L1-in-process / L2-shared read-through
+ * pattern:
+ *   - L1: an in-process vector list, scanned locally (fast, offline-capable).
+ *   - L2: an optional shared backend (e.g. the BuilderForce.ai gateway vector
+ *         store) so a hit on one surface — web or agent — benefits the other.
+ *
+ * Fully portable: the embedder and the L2 backend are injected, so the same
+ * class runs in the browser (WebGPU SSM + native fetch) and in Node (the agent's
+ * `@webgpu/node` SSM + fetch) with no environment-specific forks.
+ */
+/** Produces an embedding vector for a piece of text (the on-device SSM, typically). */
+export type Embedder = (text: string) => Promise<Float32Array>;
+/**
+ * The shared (L2) cache tier. Implemented by `FetchSemanticCacheBackend` against
+ * the gateway, but any store satisfying this shape can be injected.
+ */
+export interface SemanticCacheBackend {
+    /** Returns the best stored entry at/above `threshold` cosine similarity, or undefined. */
+    lookup(embedding: Float32Array, threshold: number): Promise<{
+        response: string;
+        score: number;
+    } | undefined>;
+    /** Persists an embedding → response association. */
+    store(embedding: Float32Array, response: string, meta?: Record<string, unknown>): Promise<void>;
+}
+export interface SemanticCacheHit {
+    response: string;
+    /** Cosine similarity of the matched entry to the query. */
+    score: number;
+    /** Which tier served the hit. */
+    tier: 'l1' | 'l2';
+}
+export interface SemanticCacheOptions {
+    /** Embeds queries. Required — this is what makes the cache semantic. */
+    embed: Embedder;
+    /**
+     * Cosine similarity at/above which a stored entry counts as a hit.
+     * Higher = stricter (fewer false hits, lower hit rate). Default: 0.92.
+     */
+    threshold?: number;
+    /** Max L1 entries retained (oldest evicted first). Default: 500. */
+    maxEntries?: number;
+    /** Optional TTL (ms) for L1 entries. Omit for no expiry. */
+    ttlMs?: number;
+    /** Optional shared L2 backend (e.g. the gateway). */
+    l2?: SemanticCacheBackend;
+    /**
+     * When true (default), an answer served by L2 is also written into L1 so the
+     * next local lookup is a fast hit — read-through cache warming.
+     */
+    warmL1FromL2?: boolean;
+}
+export declare class SemanticCache {
+    private readonly _embed;
+    private readonly _threshold;
+    private readonly _maxEntries;
+    private readonly _ttlMs;
+    private readonly _l2;
+    private readonly _warmL1;
+    private readonly _l1;
+    private _l1Hits;
+    private _l2Hits;
+    private _misses;
+    constructor(opts: SemanticCacheOptions);
+    /**
+     * Read-through entry point: returns a cached answer for a semantically-similar
+     * prior query, otherwise runs `generate()`, stores the result in both tiers,
+     * and returns it. Embeds the query exactly once (lookup + store share it).
+     */
+    getOrGenerate(query: string, generate: () => Promise<string>, meta?: Record<string, unknown>): Promise<{
+        response: string;
+        cached: boolean;
+        tier?: 'l1' | 'l2';
+        score?: number;
+    }>;
+    /** Looks up a semantically-similar cached answer without generating on a miss. */
+    lookup(query: string): Promise<SemanticCacheHit | undefined>;
+    /** Stores a query → response association in both tiers. */
+    store(query: string, response: string, meta?: Record<string, unknown>): Promise<void>;
+    /** Drops all L1 entries. Does not touch the shared L2 backend. */
+    clear(): void;
+    /** Current L1 entry count. */
+    get size(): number;
+    /** Cumulative hit/miss counters across both tiers — for measuring savings. */
+    get stats(): {
+        l1Hits: number;
+        l2Hits: number;
+        misses: number;
+    };
+    private _lookupVec;
+    private _storeVec;
+    /** Linear cosine scan over L1, dropping expired entries en route. */
+    private _searchL1;
+    private _addL1;
+}
+//# sourceMappingURL=SemanticCache.d.ts.map

package/dist/cache/SemanticCache.d.ts.map

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

package/dist/cache/SemanticCache.js

@@ -0,0 +1,130 @@
+/**
+ * SemanticCache – an embedding-keyed read-through cache for LLM completions.
+ *
+ * Unlike the exact-match ResponseCache (which keys on the byte-identical prompt),
+ * this keys on the *meaning* of the query: it embeds the query and serves a
+ * cached answer when a stored entry is within `threshold` cosine similarity.
+ * That catches paraphrases — "fix the auth bug" ≈ "login is broken" — which is
+ * where real frontier-call avoidance (and token savings) comes from.
+ *
+ * Two tiers, mirroring the project's L1-in-process / L2-shared read-through
+ * pattern:
+ *   - L1: an in-process vector list, scanned locally (fast, offline-capable).
+ *   - L2: an optional shared backend (e.g. the BuilderForce.ai gateway vector
+ *         store) so a hit on one surface — web or agent — benefits the other.
+ *
+ * Fully portable: the embedder and the L2 backend are injected, so the same
+ * class runs in the browser (WebGPU SSM + native fetch) and in Node (the agent's
+ * `@webgpu/node` SSM + fetch) with no environment-specific forks.
+ */
+import { cosineSimilarity } from '../similarity/index.js';
+const DEFAULT_THRESHOLD = 0.92;
+const DEFAULT_MAX_ENTRIES = 500;
+export class SemanticCache {
+    _embed;
+    _threshold;
+    _maxEntries;
+    _ttlMs;
+    _l2;
+    _warmL1;
+    _l1 = [];
+    _l1Hits = 0;
+    _l2Hits = 0;
+    _misses = 0;
+    constructor(opts) {
+        this._embed = opts.embed;
+        this._threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+        this._maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this._ttlMs = opts.ttlMs;
+        this._l2 = opts.l2;
+        this._warmL1 = opts.warmL1FromL2 ?? true;
+    }
+    /**
+     * Read-through entry point: returns a cached answer for a semantically-similar
+     * prior query, otherwise runs `generate()`, stores the result in both tiers,
+     * and returns it. Embeds the query exactly once (lookup + store share it).
+     */
+    async getOrGenerate(query, generate, meta) {
+        const qv = await this._embed(query);
+        const hit = await this._lookupVec(qv);
+        if (hit)
+            return { response: hit.response, cached: true, tier: hit.tier, score: hit.score };
+        const response = await generate();
+        await this._storeVec(qv, response, meta);
+        return { response, cached: false };
+    }
+    /** Looks up a semantically-similar cached answer without generating on a miss. */
+    async lookup(query) {
+        return this._lookupVec(await this._embed(query));
+    }
+    /** Stores a query → response association in both tiers. */
+    async store(query, response, meta) {
+        await this._storeVec(await this._embed(query), response, meta);
+    }
+    /** Drops all L1 entries. Does not touch the shared L2 backend. */
+    clear() {
+        this._l1.length = 0;
+    }
+    /** Current L1 entry count. */
+    get size() {
+        return this._l1.length;
+    }
+    /** Cumulative hit/miss counters across both tiers — for measuring savings. */
+    get stats() {
+        return { l1Hits: this._l1Hits, l2Hits: this._l2Hits, misses: this._misses };
+    }
+    // ── Internals (operate on a precomputed embedding) ────────────────────────
+    async _lookupVec(qv) {
+        const local = this._searchL1(qv);
+        if (local) {
+            this._l1Hits++;
+            return { response: local.response, score: local.score, tier: 'l1' };
+        }
+        if (this._l2) {
+            // L2 is best-effort: a gateway error degrades to local-only, never throws.
+            const remote = await this._l2.lookup(qv, this._threshold).catch(() => undefined);
+            if (remote && remote.score >= this._threshold) {
+                if (this._warmL1)
+                    this._addL1(qv, remote.response);
+                this._l2Hits++;
+                return { response: remote.response, score: remote.score, tier: 'l2' };
+            }
+        }
+        this._misses++;
+        return undefined;
+    }
+    async _storeVec(qv, response, meta) {
+        this._addL1(qv, response);
+        if (this._l2) {
+            // Best-effort: failing to share to L2 must not fail the caller's request.
+            await this._l2.store(qv, response, meta).catch(() => { });
+        }
+    }
+    /** Linear cosine scan over L1, dropping expired entries en route. */
+    _searchL1(qv) {
+        const now = Date.now();
+        let best;
+        let bestScore = -Infinity;
+        for (let i = this._l1.length - 1; i >= 0; i--) {
+            const entry = this._l1[i];
+            if (this._ttlMs != null && now > entry.timestamp + this._ttlMs) {
+                this._l1.splice(i, 1);
+                continue;
+            }
+            const score = cosineSimilarity(qv, entry.embedding);
+            if (score > bestScore) {
+                bestScore = score;
+                best = entry;
+            }
+        }
+        return best && bestScore >= this._threshold
+            ? { response: best.response, score: bestScore }
+            : undefined;
+    }
+    _addL1(qv, response) {
+        this._l1.push({ embedding: qv, response, timestamp: Date.now() });
+        while (this._l1.length > this._maxEntries)
+            this._l1.shift();
+    }
+}
+//# sourceMappingURL=SemanticCache.js.map

package/dist/cache/SemanticCache.js.map

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

package/dist/cache/index.d.ts

@@ -0,0 +1,5 @@
+export { SemanticCache } from './SemanticCache.js';
+export type { Embedder, SemanticCacheBackend, SemanticCacheHit, SemanticCacheOptions, } from './SemanticCache.js';
+export { FetchSemanticCacheBackend } from './FetchSemanticCacheBackend.js';
+export type { FetchSemanticCacheBackendOptions } from './FetchSemanticCacheBackend.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACR,QAAQ,EACR,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,YAAY,EAAE,gCAAgC,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,3 @@
+export { SemanticCache } from './SemanticCache.js';
+export { FetchSemanticCacheBackend } from './FetchSemanticCacheBackend.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAOnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/distillation/DistillationEngine.d.ts

@@ -0,0 +1,107 @@
+/**
+ * DistillationEngine – JS-only online knowledge distillation.
+ *
+ * The core insight: use a transformer as a *teacher* to generate high-quality
+ * responses, then adapt the SSM *student* on those responses using WSLA.
+ * This runs entirely in the browser with no Python or full-retraining required.
+ *
+ * Distillation flow:
+ *   1. bridge.generate(input)  → teacher output
+ *   2. runtime.adapt(teacherOutput, opts.adapt)  → SSM trains on it
+ *   3. Return both results for inspection
+ */
+import type { AdaptOptions, AdaptResult } from '../session/index.js';
+import type { SSMRuntime } from '../runtime/SSMRuntime.js';
+import type { TransformerBridge, BridgeGenerateOptions } from '../bridges/TransformerBridge.js';
+export interface QualityGate {
+    /**
+     * Minimum character length of the teacher output.
+     * Outputs shorter than this are considered low quality and are skipped.
+     */
+    minLength?: number;
+    /**
+     * Maximum SSM perplexity threshold.
+     * When the SSM already achieves perplexity below this value on the teacher
+     * output, the content is considered already learned and adaptation is skipped.
+     */
+    maxPerplexity?: number;
+}
+export interface DistillOptions {
+    /**
+     * Options forwarded to `runtime.adapt()`.
+     * Default: { wsla: true, epochs: 3 }
+     * WSLA is preferred because it is fast and targets the selective
+     * projection rows — exactly the parameters that encode token routing.
+     */
+    adapt?: AdaptOptions;
+    /**
+     * Options forwarded to `bridge.generate()`.
+     */
+    generate?: BridgeGenerateOptions;
+    /**
+     * Quality gate filters that can skip adaptation for low-quality or
+     * already-learned inputs.
+     */
+    qualityGate?: QualityGate;
+}
+export interface DistillResult {
+    /** The input prompt that was distilled. */
+    input: string;
+    /** The teacher's (transformer bridge) response to the input. */
+    teacherOutput: string;
+    /** The adapt() result from training the SSM on the teacher output. */
+    adaptResult: AdaptResult;
+    /** Whether adaptation was skipped by the quality gate. */
+    skipped?: boolean;
+    /** Reason adaptation was skipped, if applicable. */
+    skipReason?: string;
+}
+export interface DistillBatchResult {
+    results: DistillResult[];
+    /** Total number of adapt epochs run across all inputs. */
+    totalEpochs: number;
+    /** Wall-clock time for the entire batch in milliseconds. */
+    totalMs: number;
+}
+export interface DistillationLog {
+    timestamp: number;
+    input: string;
+    teacherOutputLength: number;
+    skipped: boolean;
+    skipReason?: string;
+    finalLoss?: number;
+    epochs: number;
+}
+export declare class DistillationEngine {
+    private readonly _runtime;
+    private readonly _bridge;
+    private readonly _log;
+    /**
+     * @param runtime The SSMRuntime whose SSM will be trained as the student.
+     * @param bridge  The transformer bridge acting as teacher.
+     *                A bridge must be provided — distillation requires one.
+     */
+    constructor(runtime: SSMRuntime, bridge: TransformerBridge);
+    /**
+     * Runs a single distillation pass:
+     *   1. Teacher generates a response for `input`
+     *   2. Quality gate is evaluated (if configured)
+     *   3. SSM is adapted on the teacher's output (WSLA by default)
+     *
+     * The training signal is the teacher's full response — this teaches the
+     * SSM what a good response to that prompt looks like, without requiring
+     * labelled data or a loss function beyond the standard LM objective.
+     */
+    distill(input: string, opts?: DistillOptions): Promise<DistillResult>;
+    /**
+     * Runs distillation for each input in sequence.
+     * Aggregate statistics are returned alongside individual results.
+     */
+    distillBatch(inputs: string[], opts?: DistillOptions): Promise<DistillBatchResult>;
+    /**
+     * Returns a copy of the in-memory distillation log (last 200 entries).
+     */
+    getLog(): DistillationLog[];
+    private _appendLog;
+}
+//# sourceMappingURL=DistillationEngine.d.ts.map

package/dist/distillation/DistillationEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DistillationEngine.d.ts","sourceRoot":"","sources":["../../src/distillation/DistillationEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAKhG,MAAM,WAAW,WAAW;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAO,MAAM,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAG,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,EAAS,YAAY,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,EAAM,qBAAqB,CAAC;IAErC;;;OAGG;IACH,WAAW,CAAC,EAAG,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC1B,2CAA2C;IAC3C,KAAK,EAAU,MAAM,CAAC;IACtB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,WAAW,EAAI,WAAW,CAAC;IAC3B,0DAA0D;IAC1D,OAAO,CAAC,EAAO,OAAO,CAAC;IACvB,oDAAoD;IACpD,UAAU,CAAC,EAAI,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAM,aAAa,EAAE,CAAC;IAC7B,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,OAAO,EAAM,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC5B,SAAS,EAAY,MAAM,CAAC;IAC5B,KAAK,EAAgB,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAc,OAAO,CAAC;IAC7B,UAAU,CAAC,EAAU,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAW,MAAM,CAAC;IAC5B,MAAM,EAAe,MAAM,CAAC;CAC/B;AAOD,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA+B;IAEpD;;;;OAIG;gBACS,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB;IAK1D;;;;;;;;;OASG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;IA8F/E;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAkB5F;;OAEG;IACH,MAAM,IAAI,eAAe,EAAE;IAM3B,OAAO,CAAC,UAAU;CAMrB"}

package/dist/distillation/DistillationEngine.js

@@ -0,0 +1,152 @@
+/**
+ * DistillationEngine – JS-only online knowledge distillation.
+ *
+ * The core insight: use a transformer as a *teacher* to generate high-quality
+ * responses, then adapt the SSM *student* on those responses using WSLA.
+ * This runs entirely in the browser with no Python or full-retraining required.
+ *
+ * Distillation flow:
+ *   1. bridge.generate(input)  → teacher output
+ *   2. runtime.adapt(teacherOutput, opts.adapt)  → SSM trains on it
+ *   3. Return both results for inspection
+ */
+import { SSMError } from '../errors/SSMError.js';
+/** Maximum number of distillation log entries to retain in memory. */
+const MAX_LOG_ENTRIES = 200;
+// ── DistillationEngine ────────────────────────────────────────────────────────
+export class DistillationEngine {
+    _runtime;
+    _bridge;
+    _log = [];
+    /**
+     * @param runtime The SSMRuntime whose SSM will be trained as the student.
+     * @param bridge  The transformer bridge acting as teacher.
+     *                A bridge must be provided — distillation requires one.
+     */
+    constructor(runtime, bridge) {
+        this._runtime = runtime;
+        this._bridge = bridge;
+    }
+    /**
+     * Runs a single distillation pass:
+     *   1. Teacher generates a response for `input`
+     *   2. Quality gate is evaluated (if configured)
+     *   3. SSM is adapted on the teacher's output (WSLA by default)
+     *
+     * The training signal is the teacher's full response — this teaches the
+     * SSM what a good response to that prompt looks like, without requiring
+     * labelled data or a loss function beyond the standard LM objective.
+     */
+    async distill(input, opts = {}) {
+        const adaptOpts = {
+            wsla: true,
+            epochs: 3,
+            ...opts.adapt,
+        };
+        let teacherOutput;
+        try {
+            teacherOutput = await this._bridge.generate(input, opts.generate);
+        }
+        catch (err) {
+            throw new SSMError('DISTILL_FAILED', `Teacher bridge failed to generate for distillation: ${err instanceof Error ? err.message : String(err)}`, err);
+        }
+        // ── Quality gate ──────────────────────────────────────────────────────
+        if (opts.qualityGate) {
+            const gate = opts.qualityGate;
+            if (gate.minLength != null && teacherOutput.length < gate.minLength) {
+                const result = {
+                    input,
+                    teacherOutput,
+                    adaptResult: { losses: [], epochCount: 0, durationMs: 0 },
+                    skipped: true,
+                    skipReason: 'low_quality',
+                };
+                this._appendLog({
+                    input,
+                    teacherOutputLength: teacherOutput.length,
+                    skipped: true,
+                    skipReason: 'low_quality',
+                    epochs: 0,
+                });
+                return result;
+            }
+            if (gate.maxPerplexity != null) {
+                let perplexity;
+                try {
+                    perplexity = await this._runtime.evaluate(teacherOutput);
+                }
+                catch {
+                    // Evaluation failure is non-fatal — proceed with adaptation
+                }
+                if (perplexity != null && perplexity < gate.maxPerplexity) {
+                    const result = {
+                        input,
+                        teacherOutput,
+                        adaptResult: { losses: [], epochCount: 0, durationMs: 0 },
+                        skipped: true,
+                        skipReason: 'already_learned',
+                    };
+                    this._appendLog({
+                        input,
+                        teacherOutputLength: teacherOutput.length,
+                        skipped: true,
+                        skipReason: 'already_learned',
+                        epochs: 0,
+                    });
+                    return result;
+                }
+            }
+        }
+        // Train the SSM on the teacher's output.
+        // Prepend the input so the model learns the (prompt → response) mapping.
+        const trainingText = `${input}\n${teacherOutput}`;
+        let adaptResult;
+        try {
+            adaptResult = await this._runtime.adapt(trainingText, adaptOpts);
+        }
+        catch (err) {
+            throw new SSMError('DISTILL_FAILED', `SSM adaptation failed during distillation: ${err instanceof Error ? err.message : String(err)}`, err);
+        }
+        this._appendLog({
+            input,
+            teacherOutputLength: teacherOutput.length,
+            skipped: false,
+            finalLoss: adaptResult.losses.at(-1),
+            epochs: adaptResult.epochCount,
+        });
+        return { input, teacherOutput, adaptResult, skipped: false };
+    }
+    /**
+     * Runs distillation for each input in sequence.
+     * Aggregate statistics are returned alongside individual results.
+     */
+    async distillBatch(inputs, opts = {}) {
+        const startMs = Date.now();
+        const results = [];
+        let totalEpochs = 0;
+        for (const input of inputs) {
+            const result = await this.distill(input, opts);
+            results.push(result);
+            totalEpochs += result.adaptResult.epochCount;
+        }
+        return {
+            results,
+            totalEpochs,
+            totalMs: Date.now() - startMs,
+        };
+    }
+    /**
+     * Returns a copy of the in-memory distillation log (last 200 entries).
+     */
+    getLog() {
+        return this._log.slice();
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    _appendLog(entry) {
+        this._log.push({ timestamp: Date.now(), ...entry });
+        if (this._log.length > MAX_LOG_ENTRIES) {
+            this._log.shift();
+        }
+    }
+}
+//# sourceMappingURL=DistillationEngine.js.map

package/dist/distillation/DistillationEngine.js.map

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