@simulatte/doppler 0.1.3 → 0.1.5

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 canonical [Root API guide](docs/api/root.md).
 
 ## Why Doppler
 
@@ -56,16 +56,21 @@ 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' },
 ]);
 
 // LoRA hot-swap
-await model.loadLoRA('oneshift-twoshift-redshift-blueshift');
+await model.loadLoRA('https://example.com/adapters/oneshift-twoshift-redshift-blueshift/manifest.json');
 
 // 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);
 }
 ```
@@ -79,7 +84,8 @@ for await (const token of doppler('Hello', { model: 'gemma-3-1b' })) {
 
 ## Environment requirements
 
-- WebGPU-capable browser runtime is required.
+- WebGPU is required.
+- Supported runtimes: WebGPU-capable browsers, or Node with a WebGPU provider.
 - Chrome / Edge 113+ supported.
 - Firefox support varies (typically behind a flag).
 - Safari support is evolving.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simulatte/doppler",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Browser-native WebGPU inference engine for local intent and inference loops",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -14,6 +14,18 @@
     "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",
+    "lean:execution-contract:sweep": "node tools/lean-execution-contract-sweep.js",
+    "lean:execution-contract:configs": "node tools/lean-execution-contract-config-sweep.js",
+    "ci:lean:execution-contract": "node tools/lean-execution-contract-sweep.js --root models",
+    "ci:lean:execution-contract:configs": "node tools/lean-execution-contract-config-sweep.js --config-root tools/configs/conversion --manifest-root models --require-manifest-match",
+    "contracts:check": "node tools/check-contract-artifacts.js",
+    "contracts:summary": "node tools/check-contract-artifacts.js --json",
+    "contracts:check:lean": "node tools/check-contract-artifacts.js --with-lean",
+    "contracts:summary:lean": "node tools/check-contract-artifacts.js --json --with-lean",
+    "ci:contracts:check": "node tools/check-contract-artifacts.js --with-lean --lean-require-manifest-match",
+    "reports:convert:summary": "node tools/summarize-conversion-reports.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",
@@ -39,6 +51,8 @@
     "agents:freshness:strict": "node tools/verify-agent-freshness.js --strict",
     "conflicts:check": "node tools/check-merge-markers.js",
     "imports:check:browser": "node tools/check-browser-import-graph.js",
+    "api:docs:sync": "node tools/sync-api-docs.js",
+    "api:docs:check": "node tools/sync-api-docs.js --check",
     "verify:model": "node tools/doppler-cli.js verify",
     "onboarding:check": "node tools/onboarding-tooling.js check",
     "onboarding:check:strict": "node tools/onboarding-tooling.js check --strict",
@@ -51,8 +65,11 @@
     "verify": "node tools/run-registry-verify.js",
     "registry:sync:scripts": "node tools/sync-registry-scripts.js",
     "registry:sync:scripts:check": "node tools/sync-registry-scripts.js --check",
+    "registry:hf:check": "node tools/check-hf-registry.js",
+    "registry:publish:hf": "node tools/publish-hf-registry-model.js",
     "support:matrix:sync": "node tools/sync-model-support-matrix.js",
     "support:matrix:check": "node tools/sync-model-support-matrix.js --check",
+    "ci:catalog:check": "npm run registry:sync:scripts:check && npm run support:matrix:check && npm run registry:hf:check",
     "external:rdrr:index": "node tools/sync-external-rdrr-index.js",
     "external:rdrr:index:check": "node tools/sync-external-rdrr-index.js --check",
     "verify:embeddinggemma-300m": "node tools/run-registry-verify.js embeddinggemma-300m",
@@ -63,6 +80,7 @@
     "verify:google-embeddinggemma-300m": "node tools/run-registry-verify.js google-embeddinggemma-300m",
     "verify:google-embeddinggemma-300m-wq4k-ef16": "node tools/run-registry-verify.js google-embeddinggemma-300m-wq4k-ef16",
     "verify:google-gemma-3-270m-it": "node tools/run-registry-verify.js google-gemma-3-270m-it",
+    "verify:google-translategemma-4b-it": "node tools/run-registry-verify.js google-translategemma-4b-it",
     "verify:qwen-3-5-0-8b": "node tools/run-registry-verify.js qwen-3-5-0-8b",
     "verify:qwen-3-5-0-8b-wq4k-ef16-hf16-f16": "node tools/run-registry-verify.js qwen-3-5-0-8b-wq4k-ef16-hf16-f16",
     "verify:qwen-3-5-2b": "node tools/run-registry-verify.js qwen-3-5-2b",
@@ -70,7 +88,10 @@
     "verify:qwen-qwen3.5-0.8b": "node tools/run-registry-verify.js qwen-qwen3.5-0.8b",
     "verify:qwen-qwen3.5-2b": "node tools/run-registry-verify.js qwen-qwen3.5-2b",
     "verify:qwen3-0.8b": "node tools/run-registry-verify.js qwen3-0.8b",
-    "verify:qwen3-2b": "node tools/run-registry-verify.js qwen3-2b"
+    "verify:qwen3-2b": "node tools/run-registry-verify.js qwen3-2b",
+    "verify:translategemma": "node tools/run-registry-verify.js translategemma",
+    "verify:translategemma-4b": "node tools/run-registry-verify.js translategemma-4b",
+    "verify:translategemma-4b-it-wq4k-ef16-hf16": "node tools/run-registry-verify.js translategemma-4b-it-wq4k-ef16-hf16"
   },
   "exports": {
     ".": {
@@ -100,8 +121,7 @@
     "./energy": {
       "types": "./src/energy/index.d.ts",
       "import": "./src/energy/index.js"
-    },
-    "./*": "./src/*"
+    }
   },
   "repository": {
     "type": "git",
@@ -138,5 +158,8 @@
     "jest": "^30.2.0",
     "onnxruntime-web": "^1.24.1",
     "playwright": "^1.58.2"
+  },
+  "optionalDependencies": {
+    "@simulatte/webgpu-doe": "0.1.x"
   }
 }

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

@@ -0,0 +1 @@
+export * from './doppler-api.d.ts';

package/src/client/doppler-api.browser.js

@@ -0,0 +1,288 @@
+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 { buildQuickstartModelBaseUrl, listQuickstartModels, resolveQuickstartModel } from './doppler-registry.js';
+
+const convenienceModelCache = new Map();
+const inFlightLoadCache = new Map();
+
+function emitLoadProgress(callback, phase, percent, message) {
+  if (typeof callback !== 'function') return;
+  callback({ phase, percent, message });
+}
+
+async function ensureWebGPUAvailable() {
+  if (typeof globalThis.navigator !== 'undefined' && globalThis.navigator?.gpu) {
+    return;
+  }
+  throw new Error('WebGPU is unavailable. Run in a WebGPU-capable browser.');
+}
+
+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,
+    };
+  }
+  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 = {}) {
+  if (!options || typeof options !== 'object' || options.model == null) {
+    throw new Error('doppler.text() requires options.model.');
+  }
+  const model = await getCachedModel(options.model, { onProgress: options.onProgress });
+  return model.generateText(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* run() {
+    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 cacheKey = resolved.modelId;
+  const cached = convenienceModelCache.get(cacheKey);
+  if (!cached) return false;
+  await cached.unload();
+  convenienceModelCache.delete(cacheKey);
+  return true;
+};
+
+doppler.evictAll = async function evictAll() {
+  const cachedModels = Array.from(convenienceModelCache.values());
+  convenienceModelCache.clear();
+  await Promise.allSettled(cachedModels.map((model) => model.unload()));
+};
+
+doppler.listModels = async function listModels() {
+  const models = await listQuickstartModels();
+  return models.map((entry) => entry.aliases[0] || entry.modelId);
+};

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;