@simulatte/doppler 0.1.3 → 0.1.4

package/README.md

@@ -15,14 +15,14 @@ npm install @simulatte/doppler
 ```js
 import { doppler } from '@simulatte/doppler';
 
-const model = await doppler.load('gemma-3-1b');
+const model = await doppler.load('gemma3-270m');
 
 for await (const token of model.generate('Hello, world')) {
   process.stdout.write(token);
 }
 ```
 
-Tokens stream from a native `AsyncGenerator`. See [more examples](#more-examples) below or the full [API contract](docs/doppler-api-contract.md).
+Registry IDs resolve to hosted RDRR artifacts from `Clocksmith/rdrr` by default. Tokens stream from a native `AsyncGenerator`. See [more examples](#more-examples) below or the full [API contract](docs/doppler-api-contract.md).
 
 ## Why Doppler
 
@@ -56,6 +56,11 @@ Snapshot artifacts:
 // Non-streaming
 const text = await model.generateText('Explain WebGPU in one sentence');
 
+// Load with progress logging
+const modelWithProgress = await doppler.load('gemma3-270m', {
+  onProgress: ({ message }) => console.log(`[doppler] ${message}`),
+});
+
 // Chat
 const reply = await model.chatText([
   { role: 'user', content: 'Write a dispatch that outruns its own light cone' },
@@ -65,7 +70,7 @@ const reply = await model.chatText([
 await model.loadLoRA('oneshift-twoshift-redshift-blueshift');
 
 // Convenience shorthand (caches model automatically)
-for await (const token of doppler('Hello', { model: 'gemma-3-1b' })) {
+for await (const token of doppler('Hello', { model: 'gemma3-270m' })) {
   process.stdout.write(token);
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simulatte/doppler",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Browser-native WebGPU inference engine for local intent and inference loops",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -14,6 +14,8 @@
     "manifest-refresh": "node tools/refresh-converted-manifest.js",
     "debug": "node tools/doppler-cli.js debug",
     "bench": "node tools/doppler-cli.js bench",
+    "lean:check": "./lean/check.sh",
+    "lean:execution-contract": "node tools/lean-execution-contract.js",
     "bench:chart": "node ./benchmarks/vendors/compare-chart.js",
     "bench:chart:readme": "node ./benchmarks/vendors/compare-chart.js --preset readme-evidence",
     "bench:architecture:chart": "node ./benchmarks/vendors/generate-architecture-overview-svg.js",

package/src/client/doppler-api.d.ts

@@ -0,0 +1,80 @@
+import type { RDRRManifest } from '../formats/rdrr/index.js';
+import type { GenerateOptions, KVCacheSnapshot } from '../generation/index.js';
+import type { ChatMessage } from '../inference/pipelines/text/chat-format.js';
+import type { LoRAManifest } from '../adapters/lora-loader.js';
+
+export interface DopplerLoadProgress {
+  phase: 'resolve' | 'manifest' | 'load' | 'ready';
+  percent: number;
+  message: string;
+}
+
+export interface DopplerLoadOptions {
+  onProgress?: (event: DopplerLoadProgress) => void;
+  runtimeConfig?: Record<string, unknown>;
+}
+
+export interface DopplerCallOptions extends GenerateOptions {
+  model: string | { url: string };
+  onProgress?: (event: DopplerLoadProgress) => void;
+}
+
+export interface DopplerChatResponse {
+  content: string;
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+export interface DopplerModel {
+  generate(prompt: string, options?: GenerateOptions): AsyncGenerator<string, void, void>;
+  generateText(prompt: string, options?: GenerateOptions): Promise<string>;
+  chat(messages: ChatMessage[], options?: GenerateOptions): AsyncGenerator<string, void, void>;
+  chatText(messages: ChatMessage[], options?: GenerateOptions): Promise<DopplerChatResponse>;
+  loadLoRA(adapter: string | LoRAManifest): Promise<void>;
+  unloadLoRA(): Promise<void>;
+  unload(): Promise<void>;
+  readonly activeLoRA: string | null;
+  readonly loaded: boolean;
+  readonly modelId: string;
+  readonly manifest: RDRRManifest;
+  readonly deviceInfo: Record<string, unknown> | null;
+  readonly advanced: {
+    prefillKV(prompt: string, options?: GenerateOptions): Promise<KVCacheSnapshot>;
+    generateWithPrefixKV(
+      prefix: KVCacheSnapshot,
+      prompt: string,
+      options?: GenerateOptions
+    ): AsyncGenerator<string, void, void>;
+  };
+}
+
+export interface DopplerNamespace {
+  (prompt: string, options: DopplerCallOptions): AsyncGenerator<string, void, void>;
+  load(
+    model: string | { url: string } | { manifest: RDRRManifest; baseUrl?: string },
+    options?: DopplerLoadOptions
+  ): Promise<DopplerModel>;
+  text(prompt: string, options: DopplerCallOptions): Promise<string>;
+  chat(messages: ChatMessage[], options: DopplerCallOptions): AsyncGenerator<string, void, void>;
+  chatText(messages: ChatMessage[], options: DopplerCallOptions): Promise<DopplerChatResponse>;
+  evict(model: string | { url: string }): Promise<boolean>;
+  evictAll(): Promise<void>;
+  listModels(): Promise<string[]>;
+}
+
+export declare function load(
+  model: string | { url: string } | { manifest: RDRRManifest; baseUrl?: string },
+  options?: DopplerLoadOptions
+): Promise<DopplerModel>;
+
+export declare function createDefaultNodeLoadProgressLogger(): (event: DopplerLoadProgress) => void;
+
+export declare function resolveLoadProgressHandlers(options?: DopplerLoadOptions): {
+  userProgress: ((event: DopplerLoadProgress) => void) | null;
+  pipelineProgress: ((event: DopplerLoadProgress) => void) | null;
+};
+
+export declare const doppler: DopplerNamespace;

package/src/client/doppler-api.js

@@ -0,0 +1,298 @@
+import { loadLoRAFromManifest, loadLoRAFromUrl } from '../adapters/lora-loader.js';
+import { log } from '../debug/index.js';
+import { getManifestUrl, parseManifest } from '../formats/rdrr/index.js';
+import { createPipeline } from '../generation/index.js';
+import { getKernelCapabilities } from '../gpu/device.js';
+import { formatChatMessages } from '../inference/pipelines/text/chat-format.js';
+import { bootstrapNodeWebGPU } from '../tooling/node-webgpu.js';
+import { buildQuickstartModelBaseUrl, listQuickstartModels, resolveQuickstartModel } from './doppler-registry.js';
+
+const convenienceModelCache = new Map();
+const inFlightLoadCache = new Map();
+
+function isNodeRuntime() {
+  return typeof process !== 'undefined'
+    && typeof process.versions === 'object'
+    && typeof process.versions.node === 'string';
+}
+
+async function ensureWebGPUAvailable() {
+  if (typeof globalThis.navigator !== 'undefined' && globalThis.navigator?.gpu) {
+    return;
+  }
+  if (isNodeRuntime()) {
+    const result = await bootstrapNodeWebGPU();
+    if (result.ok && globalThis.navigator?.gpu) {
+      return;
+    }
+  }
+  throw new Error('WebGPU is unavailable. Install a Node WebGPU provider or run in a WebGPU-capable browser.');
+}
+
+function emitLoadProgress(callback, phase, percent, message) {
+  if (typeof callback !== 'function') return;
+  callback({ phase, percent, message });
+}
+
+export function createDefaultNodeLoadProgressLogger() {
+  return (event) => {
+    const message = typeof event?.message === 'string' ? event.message.trim() : '';
+    if (!message) return;
+    log.info('doppler', message);
+  };
+}
+
+export function resolveLoadProgressHandlers(options = {}) {
+  const onProgress = typeof options?.onProgress === 'function' ? options.onProgress : null;
+  if (onProgress) {
+    return {
+      userProgress: onProgress,
+      pipelineProgress: onProgress,
+    };
+  }
+  if (isNodeRuntime()) {
+    return {
+      userProgress: createDefaultNodeLoadProgressLogger(),
+      pipelineProgress: null,
+    };
+  }
+  return {
+    userProgress: null,
+    pipelineProgress: null,
+  };
+}
+
+async function fetchManifestFromBaseUrl(baseUrl) {
+  const response = await fetch(getManifestUrl(baseUrl));
+  if (!response.ok) {
+    throw new Error(`Failed to fetch manifest from ${baseUrl}: ${response.status}`);
+  }
+  return parseManifest(await response.text());
+}
+
+async function resolveModelSource(model) {
+  if (typeof model === 'string') {
+    const entry = await resolveQuickstartModel(model);
+    return {
+      modelId: entry.modelId,
+      baseUrl: buildQuickstartModelBaseUrl(entry),
+      manifest: null,
+    };
+  }
+  if (model && typeof model === 'object' && typeof model.url === 'string' && model.url.trim().length > 0) {
+    return {
+      modelId: model.url.trim(),
+      baseUrl: model.url.trim(),
+      manifest: null,
+    };
+  }
+  if (model && typeof model === 'object' && model.manifest && typeof model.manifest === 'object') {
+    const manifest = model.manifest;
+    const modelId = typeof manifest.modelId === 'string' && manifest.modelId.length > 0
+      ? manifest.modelId
+      : 'manifest';
+    return {
+      modelId,
+      baseUrl: typeof model.baseUrl === 'string' && model.baseUrl.length > 0 ? model.baseUrl : null,
+      manifest,
+    };
+  }
+  throw new Error('doppler.load expects a quickstart registry id, { url }, or { manifest, baseUrl? }.');
+}
+
+function countTokens(pipeline, text) {
+  if (!text || typeof text !== 'string') return 0;
+  try {
+    return pipeline?.tokenizer?.encode(text)?.length ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+function resolveChatPromptForUsage(pipeline, messages) {
+  const templateType = pipeline?.manifest?.inference?.chatTemplate?.enabled === false
+    ? null
+    : (pipeline?.manifest?.inference?.chatTemplate?.type ?? null);
+  try {
+    return formatChatMessages(messages, templateType);
+  } catch {
+    return messages.map((message) => String(message?.content ?? '')).join('\n');
+  }
+}
+
+async function collectText(iterable) {
+  let output = '';
+  for await (const token of iterable) {
+    output += token;
+  }
+  return output;
+}
+
+function createModelHandle(pipeline, resolved) {
+  return {
+    generate(prompt, options = {}) {
+      return pipeline.generate(prompt, options);
+    },
+    async generateText(prompt, options = {}) {
+      return collectText(pipeline.generate(prompt, options));
+    },
+    chat(messages, options = {}) {
+      return pipeline.generate(messages, options);
+    },
+    async chatText(messages, options = {}) {
+      const content = await collectText(pipeline.generate(messages, options));
+      const promptText = resolveChatPromptForUsage(pipeline, messages);
+      const promptTokens = countTokens(pipeline, promptText);
+      const completionTokens = countTokens(pipeline, content);
+      return {
+        content,
+        usage: {
+          promptTokens,
+          completionTokens,
+          totalTokens: promptTokens + completionTokens,
+        },
+      };
+    },
+    async loadLoRA(adapter) {
+      const lora = typeof adapter === 'string'
+        ? await loadLoRAFromUrl(adapter)
+        : await loadLoRAFromManifest(adapter);
+      pipeline.setLoRAAdapter(lora);
+    },
+    async unloadLoRA() {
+      pipeline.setLoRAAdapter(null);
+    },
+    async unload() {
+      await pipeline.unload();
+    },
+    get activeLoRA() {
+      return pipeline.getActiveLoRA()?.name ?? null;
+    },
+    get loaded() {
+      return pipeline.isLoaded === true;
+    },
+    get modelId() {
+      return resolved.modelId;
+    },
+    get manifest() {
+      return pipeline.manifest;
+    },
+    get deviceInfo() {
+      return getKernelCapabilities()?.adapterInfo ?? null;
+    },
+    advanced: {
+      prefillKV(prompt, options = {}) {
+        return pipeline.prefillKVOnly(prompt, options);
+      },
+      generateWithPrefixKV(prefix, prompt, options = {}) {
+        return pipeline.generateWithPrefixKV(prefix, prompt, options);
+      },
+    },
+  };
+}
+
+export async function load(model, options = {}) {
+  const { userProgress, pipelineProgress } = resolveLoadProgressHandlers(options);
+
+  emitLoadProgress(userProgress, 'resolve', 5, 'Resolving model');
+  const resolved = await resolveModelSource(model);
+  await ensureWebGPUAvailable();
+
+  emitLoadProgress(userProgress, 'manifest', 15, 'Fetching manifest');
+  const manifest = resolved.manifest ?? await fetchManifestFromBaseUrl(resolved.baseUrl);
+
+  emitLoadProgress(userProgress, 'load', 25, 'Loading weights');
+  const pipeline = await createPipeline(manifest, {
+    baseUrl: resolved.baseUrl ?? undefined,
+    runtimeConfig: options.runtimeConfig,
+    onProgress: pipelineProgress
+      ? (progress) => emitLoadProgress(
+        pipelineProgress,
+        'load',
+        Math.max(25, Math.min(99, Math.round(progress.percent))),
+        progress.message || 'Loading weights'
+      )
+      : undefined,
+  });
+
+  emitLoadProgress(userProgress, 'ready', 100, 'Model ready');
+  return createModelHandle(pipeline, resolved);
+}
+
+async function getCachedModel(model, options = {}) {
+  const resolved = await resolveModelSource(model);
+  const cacheKey = resolved.modelId;
+  const cached = convenienceModelCache.get(cacheKey);
+  if (cached?.loaded) {
+    return cached;
+  }
+  if (cached && !cached.loaded) {
+    convenienceModelCache.delete(cacheKey);
+  }
+  if (!inFlightLoadCache.has(cacheKey)) {
+    inFlightLoadCache.set(cacheKey, load(model, options).then((instance) => {
+      convenienceModelCache.set(cacheKey, instance);
+      inFlightLoadCache.delete(cacheKey);
+      return instance;
+    }).catch((error) => {
+      inFlightLoadCache.delete(cacheKey);
+      throw error;
+    }));
+  }
+  return inFlightLoadCache.get(cacheKey);
+}
+
+async function* dopplerGenerate(prompt, options = {}) {
+  if (!options || typeof options !== 'object' || options.model == null) {
+    throw new Error('doppler() requires options.model.');
+  }
+  if (options.runtimeConfig !== undefined || options.runtimePreset !== undefined) {
+    throw new Error('doppler() does not accept load-affecting options. Use doppler.load(model, options) instead.');
+  }
+  const model = await getCachedModel(options.model, { onProgress: options.onProgress });
+  yield* model.generate(prompt, options);
+}
+
+export function doppler(prompt, options) {
+  return dopplerGenerate(prompt, options);
+}
+
+doppler.load = load;
+doppler.text = async function text(prompt, options) {
+  return collectText(doppler(prompt, options));
+};
+doppler.chat = function chat(messages, options = {}) {
+  if (!options || typeof options !== 'object' || options.model == null) {
+    throw new Error('doppler.chat() requires options.model.');
+  }
+  return (async function* () {
+    const model = await getCachedModel(options.model, { onProgress: options.onProgress });
+    yield* model.chat(messages, options);
+  }());
+};
+doppler.chatText = async function chatText(messages, options = {}) {
+  if (!options || typeof options !== 'object' || options.model == null) {
+    throw new Error('doppler.chatText() requires options.model.');
+  }
+  const model = await getCachedModel(options.model, { onProgress: options.onProgress });
+  return model.chatText(messages, options);
+};
+doppler.evict = async function evict(model) {
+  const resolved = await resolveModelSource(model);
+  const cached = convenienceModelCache.get(resolved.modelId);
+  if (!cached) {
+    return false;
+  }
+  convenienceModelCache.delete(resolved.modelId);
+  await cached.unload();
+  return true;
+};
+doppler.evictAll = async function evictAll() {
+  const cached = [...convenienceModelCache.values()];
+  convenienceModelCache.clear();
+  await Promise.all(cached.map((entry) => entry.unload()));
+};
+doppler.listModels = async function listModels() {
+  const models = await listQuickstartModels();
+  return models.map((entry) => entry.modelId);
+};

package/src/client/doppler-registry.d.ts

@@ -0,0 +1,23 @@
+export interface QuickstartRegistryEntry {
+  modelId: string;
+  aliases: string[];
+  modes: string[];
+  hf: {
+    repoId: string;
+    revision: string | null;
+    path: string;
+  } | null;
+}
+
+export declare function listQuickstartModels(): Promise<Array<{
+  modelId: string;
+  aliases: string[];
+  modes: string[];
+}>>;
+
+export declare function resolveQuickstartModel(model: string): Promise<QuickstartRegistryEntry>;
+
+export declare function buildQuickstartModelBaseUrl(
+  entry: QuickstartRegistryEntry,
+  options?: { cdnBasePath?: string }
+): string;

package/src/client/doppler-registry.js

@@ -0,0 +1,88 @@
+import { getCdnBasePath } from '../storage/download-types.js';
+import { loadJson } from '../utils/load-json.js';
+
+let registryPromise = null;
+
+function normalizeEntry(entry) {
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+  const modelId = typeof entry.modelId === 'string' ? entry.modelId.trim() : '';
+  if (!modelId) {
+    return null;
+  }
+  return {
+    modelId,
+    aliases: Array.isArray(entry.aliases)
+      ? entry.aliases.filter((alias) => typeof alias === 'string' && alias.trim().length > 0)
+      : [],
+    modes: Array.isArray(entry.modes)
+      ? entry.modes.filter((mode) => typeof mode === 'string' && mode.trim().length > 0)
+      : [],
+    hf: entry.hf && typeof entry.hf === 'object'
+      ? {
+        repoId: typeof entry.hf.repoId === 'string' ? entry.hf.repoId.trim() : '',
+        revision: typeof entry.hf.revision === 'string' && entry.hf.revision.trim().length > 0
+          ? entry.hf.revision.trim()
+          : null,
+        path: typeof entry.hf.path === 'string' ? entry.hf.path.trim() : '',
+      }
+      : null,
+  };
+}
+
+async function loadRegistry() {
+  if (!registryPromise) {
+    registryPromise = loadJson(
+      './doppler-registry.json',
+      import.meta.url,
+      'Failed to load Doppler quickstart registry'
+    ).then((raw) => {
+      const entries = Array.isArray(raw?.models)
+        ? raw.models.map(normalizeEntry).filter(Boolean)
+        : [];
+      return { models: entries };
+    });
+  }
+  return registryPromise;
+}
+
+export async function listQuickstartModels() {
+  const registry = await loadRegistry();
+  return registry.models.map((entry) => ({
+    modelId: entry.modelId,
+    aliases: [...entry.aliases],
+    modes: [...entry.modes],
+  }));
+}
+
+export async function resolveQuickstartModel(model) {
+  const requested = typeof model === 'string' ? model.trim() : '';
+  if (!requested) {
+    throw new Error('Quickstart model id is required.');
+  }
+
+  const registry = await loadRegistry();
+  const resolved = registry.models.find((entry) => (
+    entry.modelId === requested || entry.aliases.includes(requested)
+  ));
+  if (resolved) {
+    return resolved;
+  }
+
+  const available = registry.models.map((entry) => entry.modelId).join(', ');
+  throw new Error(`Unknown quickstart model "${requested}". Available: ${available}`);
+}
+
+export function buildQuickstartModelBaseUrl(entry, options = {}) {
+  if (!entry?.hf?.repoId || !entry?.hf?.path) {
+    throw new Error(`Quickstart model "${entry?.modelId ?? 'unknown'}" does not have a hosted Hugging Face source.`);
+  }
+  const cdnBasePath = typeof options.cdnBasePath === 'string' && options.cdnBasePath.length > 0
+    ? options.cdnBasePath
+    : (getCdnBasePath() || 'https://huggingface.co');
+  const revision = entry.hf.revision || 'main';
+  const base = cdnBasePath.replace(/\/$/, '');
+  const path = entry.hf.path.replace(/^\/+/, '');
+  return `${base}/${entry.hf.repoId}/resolve/${revision}/${path}`;
+}

package/src/client/doppler-registry.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "source": "Clocksmith/rdrr",
+  "models": [
+    {
+      "modelId": "gemma-3-270m-it-wq4k-ef16-hf16",
+      "aliases": [
+        "gemma3-270m",
+        "google/gemma-3-270m-it",
+        "gemma-3-270m-it-wq4k-ef16",
+        "gemma-3-270m-it-wq4k-ef16-hf16-f32"
+      ],
+      "modes": [
+        "run"
+      ],
+      "hf": {
+        "repoId": "Clocksmith/rdrr",
+        "revision": "4efe64a914892e98be50842aeb16c3b648cc68a5",
+        "path": "models/gemma-3-270m-it-wq4k-ef16"
+      }
+    },
+    {
+      "modelId": "google-embeddinggemma-300m-wq4k-ef16",
+      "aliases": [
+        "embeddinggemma-300m",
+        "google/embeddinggemma-300m",
+        "google-embeddinggemma-300m-wq4k-ef16"
+      ],
+      "modes": [
+        "embedding"
+      ],
+      "hf": {
+        "repoId": "Clocksmith/rdrr",
+        "revision": "4efe64a914892e98be50842aeb16c3b648cc68a5",
+        "path": "models/google-embeddinggemma-300m-wq4k-ef16"
+      }
+    }
+  ]
+}

package/src/config/execution-contract-check.d.ts

@@ -0,0 +1,49 @@
+export interface ExecutionContractStepFacts {
+  id: string;
+  phase: 'prefill' | 'decode' | 'both';
+  opClass: 'attention' | 'embed' | 'norm' | 'projection' | 'residual' | 'sample' | 'other';
+}
+
+export interface ExecutionContractSessionFacts {
+  layout: 'contiguous' | 'paged' | 'tiered' | 'bdpa';
+  disableCommandBatching: boolean;
+  decodeBatchSize: number;
+  headDim: number;
+  kvLen: number;
+  coldQuantMode: 'none' | 'int8' | 'int4';
+}
+
+export interface ExecutionContractFacts {
+  modelId: string;
+  session: ExecutionContractSessionFacts;
+  steps: ExecutionContractStepFacts[];
+}
+
+export interface ExecutionContractCheckResult {
+  id: string;
+  ok: boolean;
+}
+
+export interface ExecutionContractValidationResult {
+  ok: boolean;
+  errors: string[];
+  checks: ExecutionContractCheckResult[];
+}
+
+export interface ManifestExecutionContractValidationResult extends ExecutionContractValidationResult {
+  facts: ExecutionContractFacts;
+}
+
+export declare function sanitizeLeanModuleName(value: unknown): string;
+
+export declare function extractExecutionContractFacts(
+  manifest: Record<string, unknown>
+): ExecutionContractFacts;
+
+export declare function validateExecutionContractFacts(
+  facts: ExecutionContractFacts
+): ExecutionContractValidationResult;
+
+export declare function validateManifestExecutionContract(
+  manifest: Record<string, unknown>
+): ManifestExecutionContractValidationResult;