@missionsquad/browserai 0.1.0

package/src/history.ts

@@ -0,0 +1,257 @@
+import type { ModelPreset } from "./models.js";
+import type { StorageLike } from "./config.js";
+
+/**
+ * Run-history persistence + aggregation. Ported from small-ai with the storage injected: pass any
+ * `StorageLike` (or `null` for in-memory only); the default is `globalThis.localStorage` when present.
+ */
+
+/** Suggested task keys for logged runs (hosts may use their own strings). */
+export type RunCaseKey = "json" | "chat" | "summarize" | "classify" | "qa" | "voice" | "vision";
+
+export type ModelVendor =
+  | "qwen"
+  | "google"
+  | "meta"
+  | "openai"
+  | "ibm"
+  | "microsoft"
+  | "nvidia"
+  | "liquid"
+  | "huggingface"
+  | "mistral"
+  | "other";
+
+/**
+ * One logged generation. This is the persisted shape, so every field is a primitive and the
+ * set is intentionally minimal: exactly what comparison views need to rebuild their aggregates
+ * (decode/ttft by model, run log) without storing full prompts/outputs. Storing raw text or
+ * per-token arrays would blow up the storage footprint, so those are excluded.
+ */
+export type RunRecord = {
+  /** Epoch milliseconds. */
+  ts: number;
+  /** Model short name, e.g. "Qwen3.5 0.8B". */
+  model: string;
+  /** Derived vendor bucket for filtering/labels. */
+  vendor: ModelVendor;
+  /** Backend used for the run. */
+  backend: "webllm" | "transformers-js";
+  /** Task key ({@link RunCaseKey} suggested; any non-empty string accepted). */
+  case: string;
+  promptTokens: number;
+  completionTokens: number;
+  /** Decode speed in tokens/sec. */
+  decode: number;
+  /** Time to first token in seconds. */
+  ttft: number;
+  /** Measured wall-clock time in milliseconds. */
+  totalMs: number;
+  /** Measured completion tokens/sec over wall-clock time. */
+  measured: number;
+};
+
+export type ModelAggregate = {
+  model: string;
+  vendor: ModelVendor;
+  runs: number;
+  decode: number;
+  ttft: number;
+  totalMs: number;
+  measured: number;
+};
+
+export const DEFAULT_HISTORY_KEY = "browserai:v1:history";
+export const DEFAULT_HISTORY_MAX_RECORDS = 200;
+
+const VALID_VENDORS = new Set<ModelVendor>([
+  "qwen",
+  "google",
+  "meta",
+  "openai",
+  "ibm",
+  "microsoft",
+  "nvidia",
+  "liquid",
+  "huggingface",
+  "mistral",
+  "other",
+]);
+
+export type RunHistoryOptions = {
+  /** Persistence. Defaults to `globalThis.localStorage` when available; `null` = in-memory only. */
+  storage?: StorageLike | null;
+  key?: string;
+  maxRecords?: number;
+};
+
+function defaultStorage(): StorageLike | null {
+  try {
+    // `localStorage` can throw in private-mode / sandboxed contexts; history becomes ephemeral.
+    return (globalThis as { localStorage?: StorageLike }).localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function coerceRecord(value: unknown): RunRecord | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  const numericKeys = ["ts", "promptTokens", "completionTokens", "decode", "ttft", "totalMs", "measured"] as const;
+  for (const key of numericKeys) {
+    if (!isFiniteNumber(record[key])) return null;
+  }
+  if (typeof record.model !== "string" || typeof record.case !== "string" || record.case.length === 0) return null;
+
+  return {
+    ts: record.ts as number,
+    model: record.model,
+    vendor: VALID_VENDORS.has(record.vendor as ModelVendor) ? (record.vendor as ModelVendor) : "other",
+    backend: record.backend === "transformers-js" ? "transformers-js" : "webllm",
+    case: record.case,
+    promptTokens: record.promptTokens as number,
+    completionTokens: record.completionTokens as number,
+    decode: record.decode as number,
+    ttft: record.ttft as number,
+    totalMs: record.totalMs as number,
+    measured: record.measured as number,
+  };
+}
+
+/**
+ * A persisted, capped run log (newest first). All storage errors are swallowed: quota failures and
+ * unavailable storage degrade to in-memory history rather than breaking generation flows.
+ */
+export class RunHistoryStore {
+  readonly #storage: StorageLike | null;
+  readonly #key: string;
+  readonly #maxRecords: number;
+  #records: RunRecord[];
+
+  constructor(options: RunHistoryOptions = {}) {
+    this.#storage = options.storage === undefined ? defaultStorage() : options.storage;
+    this.#key = options.key ?? DEFAULT_HISTORY_KEY;
+    this.#maxRecords = options.maxRecords ?? DEFAULT_HISTORY_MAX_RECORDS;
+    this.#records = this.#load();
+  }
+
+  /** The in-memory records, newest first. */
+  get records(): readonly RunRecord[] {
+    return this.#records;
+  }
+
+  /** Prepend a record and persist. Returns the updated list. */
+  append(record: RunRecord): readonly RunRecord[] {
+    this.#records = [record, ...this.#records].slice(0, this.#maxRecords);
+    this.#persist(this.#records);
+    return this.#records;
+  }
+
+  /** Overwrite the history (e.g. after deleting selected rows). */
+  replace(records: RunRecord[]): void {
+    this.#records = records.slice(0, this.#maxRecords);
+    this.#persist(this.#records);
+  }
+
+  clear(): void {
+    this.#records = [];
+    try {
+      this.#storage?.removeItem(this.#key);
+    } catch {
+      // Clearing is best-effort.
+    }
+  }
+
+  aggregateByModel(caseFilter: string | "all" = "all"): ModelAggregate[] {
+    return aggregateByModel(this.#records, caseFilter);
+  }
+
+  #load(): RunRecord[] {
+    if (!this.#storage) return [];
+    try {
+      const raw = this.#storage.getItem(this.#key);
+      if (!raw) return [];
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed)) return [];
+      return parsed.map(coerceRecord).filter((record): record is RunRecord => record !== null);
+    } catch {
+      return [];
+    }
+  }
+
+  #persist(records: RunRecord[]): void {
+    if (!this.#storage) return;
+    try {
+      this.#storage.setItem(this.#key, JSON.stringify(records));
+    } catch {
+      // Quota errors are non-fatal; the list still lives in memory for this session.
+    }
+  }
+}
+
+/**
+ * Derive a vendor bucket from a preset. Uses explicit id/name matching rather than the repo owner
+ * so re-hosted artifacts (e.g. onnx-community mirrors) still map to the true model vendor.
+ */
+export function vendorForModel(preset: ModelPreset): ModelVendor {
+  const haystack = `${preset.id} ${preset.shortName}`.toLowerCase();
+  if (haystack.includes("qwen")) return "qwen";
+  if (haystack.includes("gemma")) return "google";
+  if (haystack.includes("llama") || haystack.includes("hermes")) return "meta";
+  if (haystack.includes("whisper")) return "openai";
+  if (haystack.includes("granite")) return "ibm";
+  if (haystack.includes("phi")) return "microsoft";
+  if (haystack.includes("nemotron") || haystack.includes("parakeet")) return "nvidia";
+  if (haystack.includes("lfm") || haystack.includes("liquid")) return "liquid";
+  if (haystack.includes("smollm") || haystack.includes("smolvlm")) return "huggingface";
+  if (haystack.includes("mistral") || haystack.includes("ministral") || haystack.includes("voxtral")) return "mistral";
+  if (haystack.includes("olmo")) return "other";
+  if (haystack.includes("minicpm")) return "other";
+  return "other";
+}
+
+export const VENDOR_LABELS: Record<ModelVendor, string> = {
+  qwen: "Qwen",
+  google: "Google",
+  meta: "Meta",
+  openai: "OpenAI",
+  ibm: "IBM",
+  microsoft: "Microsoft",
+  nvidia: "NVIDIA",
+  liquid: "Liquid",
+  huggingface: "HuggingFace",
+  mistral: "Mistral",
+  other: "Other",
+};
+
+/**
+ * Group runs by model (optionally filtered by case) and average the per-run metrics.
+ */
+export function aggregateByModel(history: readonly RunRecord[], caseFilter: string | "all"): ModelAggregate[] {
+  const buckets = new Map<string, { vendor: ModelVendor; runs: number; decode: number; ttft: number; totalMs: number; measured: number }>();
+
+  for (const record of history) {
+    if (caseFilter !== "all" && record.case !== caseFilter) continue;
+    const bucket = buckets.get(record.model) ?? { vendor: record.vendor, runs: 0, decode: 0, ttft: 0, totalMs: 0, measured: 0 };
+    bucket.runs += 1;
+    bucket.decode += record.decode;
+    bucket.ttft += record.ttft;
+    bucket.totalMs += record.totalMs;
+    bucket.measured += record.measured;
+    buckets.set(record.model, bucket);
+  }
+
+  return Array.from(buckets.entries()).map(([model, bucket]) => ({
+    model,
+    vendor: bucket.vendor,
+    runs: bucket.runs,
+    decode: bucket.decode / bucket.runs,
+    ttft: bucket.ttft / bucket.runs,
+    totalMs: bucket.totalMs / bucket.runs,
+    measured: bucket.measured / bucket.runs,
+  }));
+}

package/src/index.ts

@@ -0,0 +1,203 @@
+/**
+ * @missionsquad/browserai — run small open AI models entirely in the browser with WebGPU.
+ *
+ * Core entry points:
+ * - {@link BrowserAI} — model catalog + capability-slot manager + inference façade.
+ * - {@link VoicePipeline} — headless press-to-talk voice assistant (mic → STT → LLM → TTS).
+ */
+
+// Client
+export { BrowserAI, buildModelCacheTarget, normalizeContextLength } from "./client.js";
+export type { BrowserAIEvents, GenerateTextOptions, LoadOptions, LoadProgress, LoadedModel, StreamingTtsSession, TtsOverrides } from "./client.js";
+
+// Configuration
+export { DEFAULT_CONTEXT_LENGTH, resolveConfig } from "./config.js";
+export type { BrowserAIConfig, HistoryOptions, KokoroOptions, ResolvedConfig, StorageLike, TtsDefaults, WebLLMOptions } from "./config.js";
+
+// Errors
+export {
+  BrowserAIError,
+  formatError,
+  MicrophoneError,
+  MissingModelError,
+  ModelLoadError,
+  ProxyVerificationError,
+  UnknownModelError,
+  VoiceTurnError,
+  WebGPUUnavailableError,
+} from "./errors.js";
+
+// Events
+export { TypedEmitter } from "./events.js";
+export type { EventMap, Listener } from "./events.js";
+
+// Model catalog
+export {
+  applyCuratedModelRecordOverrides,
+  CUSTOM_MODEL_RECORD_IDS,
+  CUSTOM_MODEL_RECORDS,
+  formatMB,
+  getModelPreset,
+  KOKORO_MODEL_ID,
+  KOKORO_VOICES,
+  MODALITY_ICONS,
+  MODALITY_LABELS,
+  MODEL_PRESETS,
+  MODEL_RECORD_OVERRIDES,
+  modelRepoLabel,
+  modelSlots,
+  presetModalityIn,
+  presetModalityOut,
+  presetTasks,
+  SLOT_ORDER,
+  SUPERTONIC_2_MODEL_ID,
+  SUPERTONIC_MODEL_ID,
+  SUPERTONIC_VOICES,
+  TASK_ICONS,
+  TASK_LABELS,
+  ttsVoicesForModel,
+} from "./models.js";
+export type { Modality, ModelBackend, ModelPreset, ModelTask, MultimodalRuntime, RuntimePreset, TtsVoice } from "./models.js";
+
+// Generation parameters + JSON mode
+export { buildResponseFormat, clampNumber, parseOptionalInteger, runtimeParamsFromPreset } from "./generation.js";
+export type { JsonMode, RuntimeParameters } from "./generation.js";
+
+// Text inference
+export { buildRuntimeStatsText, collectGenericStats, EMPTY_RESPONSE, generate, normalizeLatencyBreakdown } from "./inference.js";
+export type {
+  ChatMessage,
+  EngineHandles,
+  GenerateOptions,
+  GenerationResult,
+  LatencyBreakdown,
+  RuntimeStats,
+  TransformersModule,
+  TransformersTextGenerationPipeline,
+  TransformersTokenizer,
+  WebLLMUsageExtra,
+} from "./inference.js";
+
+// Multimodal runtimes (STT / TTS / VLM / Gemma)
+export {
+  capSrc,
+  DEFAULT_KOKORO_CDN,
+  describeImage,
+  disposeMultimodal,
+  generateGemmaText,
+  loadMultimodal,
+  planGemmaAudioWindows,
+  runAudioLm,
+  runGemma,
+  runVoxtralRealtime,
+  supertonicVoiceUrl,
+  supportsStreamingTts,
+  synthesize,
+  synthesizeStream,
+  transcribe,
+} from "./multimodal.js";
+export type {
+  AudioWindow,
+  GenStats,
+  KokoroModule,
+  LoadMultimodalOptions,
+  MultimodalDevice,
+  MultimodalHandle,
+  MultimodalTransformers,
+  ProgressCallback,
+  RawAudio,
+  SttResult,
+  TextTurn,
+  TtsTextSplitter,
+  VlmResult,
+} from "./multimodal.js";
+
+// JSON helpers + schema validation
+export { detectLikelyRepetition, extractJsonCandidate, normalizeModelText, parseJsonFromModel, prettyJson } from "./json.js";
+export type { JsonParseResult } from "./json.js";
+export { validateAgainstJsonSchema } from "./schema-validator.js";
+export { DEFAULT_EXTRACTION_SCHEMA, stringifySchema, stripSchemaMetadata } from "./schema.js";
+export { buildExtractionMessages, DEFAULT_EXTRACTION_INSTRUCTIONS } from "./prompt.js";
+
+// Model source (direct vs proxy) + proxy verification
+export {
+  applyContextOverride,
+  buildProxiedAppConfig,
+  buildWebLLMAppConfig,
+  modelSourceDescription,
+  proxyHuggingFaceUrl,
+  proxyModelLibraryUrl,
+  proxyModelRecord,
+  proxyRawGithubUrl,
+  TRANSFORMERS_CACHE_KEY,
+  withCustomModelRecords,
+} from "./model-source.js";
+export type { BrowserCacheBackend, ModelSourceMode } from "./model-source.js";
+export { splitHuggingFaceRepoId, verifyTransformersProxy, verifyWebLLMProxy } from "./proxy-verify.js";
+
+// Hardware probing
+export { collectHardwareSnapshot, formatBytes, formatHardwareSnapshot, modelSafetyHint } from "./hardware.js";
+export type { HardwareSnapshot } from "./hardware.js";
+
+// Model artifact cache management
+export {
+  deleteOneModelArtifactsFromBrowserStorage,
+  deleteTransformersModelArtifactsFromBrowserStorage,
+  deleteTransformersModelFromBrowserCache,
+  deleteWebLLMModelArtifactsFromBrowserStorage,
+  estimateOriginStorage,
+  getCachedModelStatus,
+  hasTransformersModelInBrowserCache,
+  matchesModelCacheTarget,
+  TRANSFORMERS_CACHE_SCOPE,
+  WEBLLM_CACHE_SCOPES,
+} from "./model-cache.js";
+export type {
+  CacheCleanupResult,
+  CacheCleanupScopeResult,
+  CachedModelStatus,
+  IndividualModelCacheStatus,
+  IndividualModelCleanupResult,
+  ModelCacheTarget,
+  StorageEstimateSnapshot,
+} from "./model-cache.js";
+
+// Metrics + run history
+export { buildMultimodalStats, runRecordFromStats, wordCountGenStats } from "./metrics.js";
+export {
+  aggregateByModel,
+  DEFAULT_HISTORY_KEY,
+  DEFAULT_HISTORY_MAX_RECORDS,
+  RunHistoryStore,
+  VENDOR_LABELS,
+  vendorForModel,
+} from "./history.js";
+export type { ModelAggregate, ModelVendor, RunCaseKey, RunHistoryOptions, RunRecord } from "./history.js";
+
+// Audio utilities
+export { AUDIO_SR, encodeWavBlob, pitchShiftBuffer } from "./audio/pcm.js";
+export { decodeAudioTo16kMono } from "./audio/decode.js";
+export { MicRecorder } from "./audio/recorder.js";
+export type { MicRecorderOptions } from "./audio/recorder.js";
+export { createStreamingAudioPlayer } from "./audio/streaming-player.js";
+export type { StreamingAudioPlayer, StreamingAudioPlayerOptions } from "./audio/streaming-player.js";
+export { clipFromRawAudio, clipPlaybackRate, playClipThroughElement, releaseClip, repitchClip, synthesizeClip } from "./audio/clip.js";
+export type { SynthClip, SynthesizeClipOptions } from "./audio/clip.js";
+
+// Text utilities
+export { stripThinkTags } from "./text-utils.js";
+
+// Voice pipeline
+export {
+  capPipelineHistory,
+  missingPipelineModels,
+  PIPELINE_HISTORY_MAX_TURNS,
+  PIPELINE_RECOMMENDED,
+  PIPELINE_SYSTEM_PROMPT,
+  PIPELINE_TASKS,
+  shouldSpeakReply,
+  streamedDelta,
+} from "./voice/helpers.js";
+export type { PipelineTask } from "./voice/helpers.js";
+export { VoicePipeline } from "./voice/voice-pipeline.js";
+export type { TurnDiscardReason, VoicePipelineEvents, VoicePipelineOptions, VoicePipelineStage } from "./voice/voice-pipeline.js";