@simulatte/doppler 0.1.9 → 0.2.0

package/src/inference/speculative.js

@@ -1,402 +0,0 @@
-function createRng(seed) {
-  let state = seed >>> 0;
-  if (!state) state = 0x6d2b79f5;
-  return () => {
-    state |= 0;
-    state = (state + 0x6d2b79f5) | 0;
-    let t = Math.imul(state ^ (state >>> 15), 1 | state);
-    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
-function coerceLogitsVector(value, label) {
-  if (value instanceof Float32Array) {
-    if (value.length === 0) {
-      throw new Error(`SpeculativeDecoder: ${label} must not be empty.`);
-    }
-    return value;
-  }
-
-  if (ArrayBuffer.isView(value)) {
-    if (value.length === 0) {
-      throw new Error(`SpeculativeDecoder: ${label} must not be empty.`);
-    }
-    return Float32Array.from(value);
-  }
-
-  if (Array.isArray(value)) {
-    if (value.length === 0) {
-      throw new Error(`SpeculativeDecoder: ${label} must not be empty.`);
-    }
-
-    if (typeof value[0] === 'number') {
-      return Float32Array.from(value);
-    }
-
-    const last = value[value.length - 1];
-    if (last instanceof Float32Array) {
-      if (last.length === 0) {
-        throw new Error(`SpeculativeDecoder: ${label} must not be empty.`);
-      }
-      return last;
-    }
-    if (ArrayBuffer.isView(last)) {
-      if (last.length === 0) {
-        throw new Error(`SpeculativeDecoder: ${label} must not be empty.`);
-      }
-      return Float32Array.from(last);
-    }
-    if (Array.isArray(last) && (last.length === 0 || typeof last[0] === 'number')) {
-      if (last.length === 0) {
-        throw new Error(`SpeculativeDecoder: ${label} must not be empty.`);
-      }
-      return Float32Array.from(last);
-    }
-  }
-
-  throw new Error(
-    `SpeculativeDecoder: ${label} must be a numeric logits vector (Float32Array or number[]).`
-  );
-}
-
-function assertTemperature(temperature, label) {
-  if (!Number.isFinite(temperature) || temperature <= 0) {
-    throw new Error(`SpeculativeDecoder: ${label} must be a positive finite number.`);
-  }
-}
-
-export class SpeculativeDecoder {
-  numDraftTokens;
-  maxRejectionRetries;
-  enableTreeDraft;
-  temperature;
-  random;
-  draftModel = null;
-  mainModel = null;
-  stats = {
-    totalDrafted: 0,
-    totalAccepted: 0,
-    totalRejected: 0,
-    averageAcceptRate: 0,
-  };
-
-  constructor(config = {}) {
-    if (config.numDraftTokens == null) {
-      throw new Error('SpeculativeDecoder requires numDraftTokens.');
-    }
-    if (config.maxRejectionRetries == null) {
-      throw new Error('SpeculativeDecoder requires maxRejectionRetries.');
-    }
-    if (config.enableTreeDraft == null) {
-      throw new Error('SpeculativeDecoder requires enableTreeDraft.');
-    }
-    if (config.temperature == null) {
-      throw new Error('SpeculativeDecoder requires temperature.');
-    }
-    if (!Number.isFinite(config.randomSeed)) {
-      throw new Error('SpeculativeDecoder requires randomSeed.');
-    }
-
-    assertTemperature(config.temperature, 'temperature');
-    this.numDraftTokens = config.numDraftTokens;
-    this.maxRejectionRetries = config.maxRejectionRetries;
-    this.enableTreeDraft = config.enableTreeDraft;
-    this.temperature = config.temperature;
-
-    this.random = createRng(Math.floor(config.randomSeed));
-  }
-
-  setDraftModel(model) {
-    this.draftModel = model;
-  }
-
-  setMainModel(model) {
-    this.mainModel = model;
-  }
-
-  async _forwardForLogits(model, inputIds, kvCache, label) {
-    const result = await model.forward(inputIds, kvCache);
-    if (!result || typeof result !== 'object') {
-      throw new Error(`SpeculativeDecoder: ${label} forward() must return an object.`);
-    }
-    return {
-      logits: coerceLogitsVector(result.logits, `${label} logits`),
-      kvCache: result.newKVCache ?? kvCache,
-    };
-  }
-
-  async generateDraftTokens(inputIds, kvCache, numTokens = this.numDraftTokens) {
-    if (!this.draftModel) {
-      throw new Error('Draft model not set');
-    }
-
-    const draftTokens = [];
-    const draftLogprobs = [];
-    let draftKVCache = kvCache?.clone?.() ?? kvCache;
-    let currentIds = [...inputIds];
-
-    for (let i = 0; i < numTokens; i++) {
-      const forwardResult = await this._forwardForLogits(
-        this.draftModel,
-        currentIds,
-        draftKVCache,
-        `draft step ${i}`
-      );
-      draftKVCache = forwardResult.kvCache;
-
-      const { token, logprob } = this.sampleToken(forwardResult.logits, this.temperature);
-      draftTokens.push(token);
-      draftLogprobs.push(logprob);
-      currentIds = [...currentIds, token];
-    }
-
-    return {
-      tokens: draftTokens,
-      logprobs: draftLogprobs,
-    };
-  }
-
-  sampleToken(logits, temperature) {
-    const logitsVector = coerceLogitsVector(logits, 'sample logits');
-    assertTemperature(temperature, 'temperature');
-    const vocabSize = logitsVector.length;
-
-    const scaledLogits = new Float32Array(vocabSize);
-    for (let i = 0; i < vocabSize; i++) {
-      scaledLogits[i] = logitsVector[i] / temperature;
-    }
-
-    const logprobs = this.logSoftmax(scaledLogits);
-    const probs = new Float32Array(vocabSize);
-    for (let i = 0; i < vocabSize; i++) {
-      probs[i] = Math.exp(logprobs[i]);
-    }
-
-    const r = this.random();
-    let cumSum = 0;
-    for (let i = 0; i < vocabSize; i++) {
-      cumSum += probs[i];
-      if (r < cumSum) {
-        return { token: i, logprob: logprobs };
-      }
-    }
-
-    return { token: vocabSize - 1, logprob: logprobs };
-  }
-
-  logSoftmax(logits) {
-    const logitsVector = coerceLogitsVector(logits, 'logSoftmax logits');
-    const n = logitsVector.length;
-    const result = new Float32Array(n);
-
-    let max = -Infinity;
-    for (let i = 0; i < n; i++) {
-      if (logitsVector[i] > max) max = logitsVector[i];
-    }
-
-    let sumExp = 0;
-    for (let i = 0; i < n; i++) {
-      sumExp += Math.exp(logitsVector[i] - max);
-    }
-    const logSumExp = max + Math.log(sumExp);
-
-    for (let i = 0; i < n; i++) {
-      result[i] = logitsVector[i] - logSumExp;
-    }
-
-    return result;
-  }
-
-  async verifyDraftTokens(inputIds, draftTokens, draftLogprobs, kvCache) {
-    if (!this.mainModel) {
-      throw new Error('Main model not set');
-    }
-    if (!Array.isArray(draftTokens) || !Array.isArray(draftLogprobs)) {
-      throw new Error('SpeculativeDecoder: draft tokens and logprobs must be arrays.');
-    }
-    if (draftTokens.length !== draftLogprobs.length) {
-      throw new Error('SpeculativeDecoder: draft token/logprob length mismatch.');
-    }
-
-    const numDraft = draftTokens.length;
-    const acceptedTokens = [];
-    let acceptedCount = 0;
-    let verifyIds = [...inputIds];
-    let verifyKVCache = kvCache?.clone?.() ?? kvCache;
-    let rejectedMainLogits = null;
-
-    for (let i = 0; i < numDraft; i++) {
-      const forwardResult = await this._forwardForLogits(
-        this.mainModel,
-        verifyIds,
-        verifyKVCache,
-        `verify step ${i}`
-      );
-      verifyKVCache = forwardResult.kvCache;
-      const mainLogits = forwardResult.logits;
-      const mainLogprob = this.logSoftmax(mainLogits);
-      const draftToken = draftTokens[i];
-      const draftLogprobVec = coerceLogitsVector(draftLogprobs[i], `draft logprobs[${i}]`);
-
-      if (!Number.isInteger(draftToken) || draftToken < 0 || draftToken >= mainLogprob.length) {
-        throw new Error(
-          `SpeculativeDecoder: draft token at index ${i} is out of vocabulary range.`
-        );
-      }
-      if (draftLogprobVec.length !== mainLogprob.length) {
-        throw new Error(
-          `SpeculativeDecoder: draft logprobs[${i}] length (${draftLogprobVec.length}) ` +
-          `does not match main logits length (${mainLogprob.length}).`
-        );
-      }
-
-      const draftLogprob = draftLogprobVec[draftToken];
-      const mainTokenLogprob = mainLogprob[draftToken];
-      const acceptProb = Math.min(1, Math.exp(mainTokenLogprob - draftLogprob));
-
-      if (this.random() < acceptProb) {
-        acceptedTokens.push(draftToken);
-        acceptedCount++;
-        verifyIds = [...verifyIds, draftToken];
-      } else {
-        rejectedMainLogits = mainLogits;
-        break;
-      }
-    }
-
-    let sampledToken;
-    if (acceptedCount === numDraft) {
-      const continuation = await this._forwardForLogits(
-        this.mainModel,
-        verifyIds,
-        verifyKVCache,
-        'verify continuation'
-      );
-      sampledToken = this.sampleToken(continuation.logits, this.temperature).token;
-    } else {
-      if (!rejectedMainLogits) {
-        throw new Error('SpeculativeDecoder: missing main logits for rejected token.');
-      }
-      const rejectedDraftLogprobs = draftLogprobs[acceptedCount];
-      if (!rejectedDraftLogprobs) {
-        throw new Error(
-          `SpeculativeDecoder: missing draft logprobs for rejected token at index ${acceptedCount}.`
-        );
-      }
-      sampledToken = this.sampleFromResidual(
-        rejectedMainLogits,
-        rejectedDraftLogprobs,
-        true
-      );
-    }
-
-    this.stats.totalDrafted += numDraft;
-    this.stats.totalAccepted += acceptedCount;
-    this.stats.totalRejected += numDraft - acceptedCount;
-    this.stats.averageAcceptRate = this.stats.totalDrafted > 0
-      ? this.stats.totalAccepted / this.stats.totalDrafted
-      : 0;
-
-    return {
-      acceptedCount,
-      acceptedTokens,
-      sampledToken,
-      allAccepted: acceptedCount === numDraft,
-    };
-  }
-
-  sampleFromResidual(mainLogits, draftLogprobs, wasRejected) {
-    const mainLogitsVec = coerceLogitsVector(mainLogits, 'residual main logits');
-    if (!wasRejected) {
-      return this.sampleToken(mainLogitsVec, this.temperature).token;
-    }
-
-    const draftLogprobVec = coerceLogitsVector(draftLogprobs, 'residual draft logprobs');
-    if (draftLogprobVec.length !== mainLogitsVec.length) {
-      throw new Error(
-        `SpeculativeDecoder: residual draft/main length mismatch (${draftLogprobVec.length} vs ${mainLogitsVec.length}).`
-      );
-    }
-
-    const vocabSize = mainLogitsVec.length;
-    const mainProbs = new Float32Array(vocabSize);
-    const draftProbs = new Float32Array(vocabSize);
-
-    const mainLogprobsArr = this.logSoftmax(mainLogitsVec);
-    for (let i = 0; i < vocabSize; i++) {
-      mainProbs[i] = Math.exp(mainLogprobsArr[i]);
-      draftProbs[i] = Math.exp(draftLogprobVec[i] ?? -Infinity);
-    }
-
-    const residual = new Float32Array(vocabSize);
-    let residualSum = 0;
-    for (let i = 0; i < vocabSize; i++) {
-      residual[i] = Math.max(0, mainProbs[i] - draftProbs[i]);
-      residualSum += residual[i];
-    }
-
-    if (residualSum > 0) {
-      const r = this.random() * residualSum;
-      let cumSum = 0;
-      for (let i = 0; i < vocabSize; i++) {
-        cumSum += residual[i];
-        if (r < cumSum) {
-          return i;
-        }
-      }
-    }
-
-    return this.sampleToken(mainLogitsVec, this.temperature).token;
-  }
-
-  async step(inputIds, mainKVCache, draftKVCache) {
-    const { tokens: draftTokens, logprobs: draftLogprobs } =
-      await this.generateDraftTokens(inputIds, draftKVCache);
-
-    const result = await this.verifyDraftTokens(
-      inputIds,
-      draftTokens,
-      draftLogprobs,
-      mainKVCache
-    );
-
-    const newTokens = [...result.acceptedTokens, result.sampledToken];
-    const draftedCount = draftTokens.length;
-
-    return {
-      newTokens,
-      mainKVCache,
-      acceptRate: draftedCount > 0 ? result.acceptedCount / draftedCount : 0,
-    };
-  }
-
-  getStats() {
-    return {
-      ...this.stats,
-      speedup: this.estimateSpeedup(),
-    };
-  }
-
-  estimateSpeedup() {
-    if (this.stats.totalDrafted === 0) return 1.0;
-
-    const acceptRate = this.stats.averageAcceptRate;
-    const k = this.numDraftTokens;
-    const draftOverhead = 0.1 * k;
-    const tokensPerCall = 1 + acceptRate * k;
-
-    return tokensPerCall / (1 + draftOverhead);
-  }
-
-  resetStats() {
-    this.stats = {
-      totalDrafted: 0,
-      totalAccepted: 0,
-      totalRejected: 0,
-      averageAcceptRate: 0,
-    };
-  }
-}
-
-export default SpeculativeDecoder;

package/src/inference/test-harness.d.ts

@@ -1,178 +0,0 @@
-/**
- * test-harness.ts - Shared Inference Test Utilities
- *
- * Common utilities for inference testing and automation:
- * - Model discovery via catalog.json
- * - URL parameter parsing for runtime config
- * - HTTP-based shard loading
- * - Pipeline initialization helpers
- *
- * Used by tests/harness.html (runtime.shared.harness.mode) and other test harnesses.
- *
- * @module inference/test-harness
- */
-
-import { type KernelCapabilities } from '../gpu/device.js';
-import { type RDRRManifest } from '../formats/rdrr/index.js';
-import { type Pipeline } from './pipelines/text.js';
-import type { RuntimeConfigSchema } from '../config/schema/index.js';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Model info returned from catalog.json
- */
-export interface ModelInfo {
-  id: string;
-  name: string;
-  path?: string;
-  numLayers?: number;
-  vocabSize?: number;
-  quantization?: string;
-  downloadSize?: number;
-  architecture?: string;
-}
-
-/**
- * Runtime overrides parsed from URL parameters
- */
-export interface RuntimeOverrides {
-  runtimeConfig?: Partial<RuntimeConfigSchema>;
-  /** Config inheritance chain for debugging (e.g., ['debug', 'default']) */
-  configChain?: string[];
-}
-
-/**
- * Options for pipeline initialization
- */
-export interface InferenceHarnessOptions {
-  /** Base URL for model files (default: inferred from model URL) */
-  baseUrl?: string;
-  /** Runtime overrides for kernel selection */
-  runtime?: RuntimeOverrides;
-  /** Progress callback */
-  onProgress?: (phase: string, progress: number, detail?: string) => void;
-  /** Log function (default: debug log) */
-  log?: (msg: string, level?: string) => void;
-}
-
-/**
- * Result of pipeline initialization
- */
-export interface InitializeResult {
-  pipeline: Pipeline;
-  manifest: RDRRManifest;
-  capabilities: KernelCapabilities;
-}
-
-// ============================================================================
-// Model Discovery
-// ============================================================================
-
-/**
- * Discover available models from the catalog.json endpoint.
- *
- * @param fallbackModels - Explicit fallback models to use when catalog fetch is unavailable
- * @returns Array of model info objects
- */
-export declare function discoverModels(
-  fallbackModels?: string[]
-): Promise<ModelInfo[]>;
-
-// ============================================================================
-// URL Parameter Parsing
-// ============================================================================
-
-/**
- * Parse runtime config from URL query parameters.
- *
- * Supported parameters:
- * - runtimeConfig: JSON-encoded runtime config
- * - configChain: JSON-encoded config chain (for debugging)
- *
- * @param searchParams - URLSearchParams to parse (default: window.location.search)
- * @returns RuntimeOverrides object
- */
-export declare function parseRuntimeOverridesFromURL(
-  searchParams?: URLSearchParams
-): RuntimeOverrides;
-
-// ============================================================================
-// Shard Loading
-// ============================================================================
-
-/**
- * Create an HTTP-based shard loader for a model.
- *
- * @param baseUrl - Base URL for the model (e.g., http://localhost:8080/models/gemma-1b-q4)
- * @param manifest - Parsed model manifest
- * @param log - Optional logging function
- * @returns Async function that loads a shard by index
- */
-export declare function createHttpShardLoader(
-  baseUrl: string,
-  manifest: RDRRManifest,
-  log?: (msg: string, level?: string) => void
-): (idx: number) => Promise<Uint8Array>;
-
-// ============================================================================
-// Pipeline Initialization
-// ============================================================================
-
-/**
- * Fetch and parse a model manifest from a URL.
- *
- * @param manifestUrl - URL to manifest.json
- * @returns Parsed manifest
- */
-export declare function fetchManifest(manifestUrl: string): Promise<RDRRManifest>;
-
-/**
- * Initialize the WebGPU device and return capabilities.
- *
- * @returns Kernel capabilities
- */
-export declare function initializeDevice(): Promise<KernelCapabilities>;
-
-/**
- * Initialize a complete inference pipeline from a model URL.
- *
- * This is a convenience function that handles:
- * 1. WebGPU device initialization
- * 2. Manifest fetching and parsing
- * 3. Pipeline creation with shard loading
- *
- * @param modelUrl - Base URL for the model directory
- * @param options - Initialization options
- * @returns Pipeline and associated info
- */
-export declare function initializeInference(
-  modelUrl: string,
-  options?: InferenceHarnessOptions
-): Promise<InitializeResult>;
-
-// ============================================================================
-// Test State (for browser automation)
-// ============================================================================
-
-/**
- * Standard test state interface for browser automation.
- */
-export interface TestState {
-  ready: boolean;
-  loading: boolean;
-  loaded: boolean;
-  generating: boolean;
-  done: boolean;
-  output: string;
-  tokens: string[];
-  errors: string[];
-  model: string | null;
-}
-
-/**
- * Create initial test state object.
- */
-export declare function createTestState(): TestState;