doppler-gpu 0.7.1 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,49 @@ Historical package notes are preserved outside the runtime archive in
4
4
  `docs/status/archive/package-changelog-through-0.6.1.md` and the earlier
5
5
  `package-changelog-through-0.4.15.md` snapshot in that directory.
6
6
 
7
+ ## [0.7.3] - 2026-11-11
8
+
9
+ ### Fixed
10
+
11
+ - The installed `doppler` and `doppler-serve` commands start when run through
12
+ npm's bin links. In 0.7.1 and 0.7.2 they exited 0 without output;
13
+ `doppler-gpu` and the library were unaffected.
14
+
15
+ ## [0.7.2] - 2026-11-11
16
+
17
+ ### Added
18
+
19
+ - `model.inspect.projectLayerOutputs({ vectors, topK })` projects recorded
20
+ hidden states through the loaded model's final normalization and output head.
21
+ It returns vocabulary-normalized probabilities explicitly labeled
22
+ `projected`. Intermediate projections are an inspection aid, not generated
23
+ tokens or evidence of causation. Hyper-connection and paired-precision plans
24
+ fail explicitly. Calls accept at most 64 vectors and 64 candidates per row.
25
+
26
+ ### Fixed
27
+
28
+ - Projection requests snapshot both vector values and row count before waiting
29
+ for execution. Mutating the caller's vector array cannot change an admitted
30
+ request's shape.
31
+
32
+ ### Limits
33
+
34
+ - Projection reads back a full vocabulary row for each input vector; recording
35
+ and projection costs are separate from uninstrumented inference performance.
36
+ - Flash-Next's 2,187-token full-logit gate remains failing and unqualified.
37
+ This release does not fix or relax that gate.
38
+
39
+ ### Comparison evidence
40
+
41
+ - The release report includes Qwen 3.5 0.8B and 2B on Apple M3 against
42
+ Transformers.js 4.3.2 / ONNX Runtime WebGPU and llama.cpp, plus Qwen3.8 27B
43
+ on Jupiter against direct ONNX Runtime WebGPU and llama.cpp Vulkan.
44
+ It retains exact prompts, artifact identities, outputs, load times and
45
+ complete-request timings. Host variability and output mismatches prevent a
46
+ general speed or quality claim; native llama.cpp remains ahead on the
47
+ retained matched-output workloads. See
48
+ [the release evidence](https://github.com/clocksmith/doppler/tree/main/reports/package-release-0.7.2).
49
+
7
50
  ## [0.7.1] - 2026-11-11
8
51
 
9
52
  Patch release. Published bytes for 0.7.0 are unchanged.
package/README.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # Doppler
2
2
 
3
+ <a href="assets/readme/doppler-demo-hero.mp4"><img src="assets/readme/doppler-demo-hero.gif" width="100%" alt="Doppler demo: a recorded Qwen 3.5 0.8B answer appears token by token beside per-layer activation changes, then one word's next-token alternatives open with their probabilities." /></a>
4
+
5
+ <sub>Recorded replay from the <a href="https://d4da.com/doppler/">demo</a>, not a live run. <a href="assets/readme/doppler-demo-hero.mp4">Full-quality video</a>.</sub>
6
+
3
7
  A JavaScript library for local model execution through WebGPU: generation,
4
8
  embeddings, reranking, and choice scoring, qualified per model and host.
5
9
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "doppler-gpu",
3
- "version": "0.7.1",
3
+ "version": "0.7.3",
4
4
  "description": "Doppler Rig prepares signed model Capsules; Doppler Run executes them locally through WebGPU for JavaScript",
5
5
  "main": "src/capsule-runtime.js",
6
6
  "types": "src/capsule-runtime.d.ts",
@@ -355,7 +355,7 @@
355
355
  "tools/convert-safetensors-node.js"
356
356
  ],
357
357
  "devDependencies": {
358
- "@huggingface/transformers": "^4.0.1",
358
+ "@huggingface/transformers": "^4.3.2",
359
359
  "@types/node": "^25.6.0",
360
360
  "@webgpu/types": "^0.1.69",
361
361
  "jest": "^30.2.0",
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  import fs from 'node:fs/promises';
4
+ import { realpathSync } from 'node:fs';
4
5
  import path from 'node:path';
5
6
  import { fileURLToPath } from 'node:url';
6
7
  import { writeProgramBundle } from '../tooling/program-bundle.js';
@@ -590,7 +591,8 @@ function isMainModule(metaUrl) {
590
591
  if (!entryPath) {
591
592
  return false;
592
593
  }
593
- return path.resolve(fileURLToPath(metaUrl)) === path.resolve(entryPath);
594
+ // npm starts bins through a symbolic link, so compare real paths.
595
+ return realpathSync(path.resolve(fileURLToPath(metaUrl))) === realpathSync(path.resolve(entryPath));
594
596
  }
595
597
 
596
598
  function flushStream(stream) {
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  import http from 'node:http';
4
+ import { realpathSync } from 'node:fs';
4
5
  import path from 'node:path';
5
6
  import process from 'node:process';
6
7
  import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -584,7 +585,8 @@ function isMainModule(metaUrl) {
584
585
  if (!entryPath) {
585
586
  return false;
586
587
  }
587
- return path.resolve(fileURLToPath(metaUrl)) === path.resolve(entryPath);
588
+ // npm starts bins through a symbolic link, so compare real paths.
589
+ return realpathSync(path.resolve(fileURLToPath(metaUrl))) === realpathSync(path.resolve(entryPath));
588
590
  }
589
591
 
590
592
  if (isMainModule(import.meta.url)) {
@@ -113,6 +113,33 @@ export declare function buildInspectionTokenRecords(
113
113
  topKSize?: number
114
114
  ): DopplerInspectionTokenRecord[];
115
115
 
116
+ export declare const LAYER_PROJECTION_SCHEMA: 'doppler.layer-projection/v1';
117
+ export declare const LAYER_PROJECTION_MAX_ROWS: 64;
118
+ export declare const LAYER_PROJECTION_MAX_TOP_K: 64;
119
+
120
+ export interface DopplerLayerProjection {
121
+ schema: typeof LAYER_PROJECTION_SCHEMA;
122
+ modelId: string;
123
+ /** What the vectors were passed through. `kind` is always `projected`: these are not tokens the model produced. */
124
+ projection: { through: ['final-normalization', 'output-head']; kind: 'projected' };
125
+ vocabSize: number;
126
+ rows: Array<{ candidates: DopplerTokenCandidate[] }>;
127
+ }
128
+
129
+ export interface DopplerTokenCandidate {
130
+ tokenId: number;
131
+ logit: number;
132
+ text: string;
133
+ probability: number | null;
134
+ }
135
+
136
+ /** The `count` highest logits with their softmax probability over the whole row. */
137
+ export declare function topCandidates(
138
+ logits: ArrayLike<number> | null | undefined,
139
+ tokenizer: { decode(ids: number[], skipSpecialTokens?: boolean, trim?: boolean): string },
140
+ count: number
141
+ ): DopplerTokenCandidate[];
142
+
116
143
  export declare function buildInspectionTokenRecord(
117
144
  tokenId: number,
118
145
  logits: Float32Array | null,
@@ -215,7 +215,13 @@ function selectedProbability(logits, tokenId) {
215
215
  return Math.exp(Number(logits[tokenId]) - maximum) / denominator;
216
216
  }
217
217
 
218
- function topCandidates(logits, tokenizer, count) {
218
+ export const LAYER_PROJECTION_SCHEMA = 'doppler.layer-projection/v1';
219
+ // One request returns a full vocabulary row per vector before the top candidates
220
+ // are kept, so both bounds limit what a single call can hold.
221
+ export const LAYER_PROJECTION_MAX_ROWS = 64;
222
+ export const LAYER_PROJECTION_MAX_TOP_K = 64;
223
+
224
+ export function topCandidates(logits, tokenizer, count) {
219
225
  if (!logits || !Number.isInteger(count) || count <= 0) return [];
220
226
  const candidates = [];
221
227
  for (let tokenId = 0; tokenId < logits.length; tokenId += 1) {
@@ -0,0 +1,46 @@
1
+ import { runPipelineOperation } from '../../inference/pipelines/shader-scoped-pipeline.js';
2
+ import {
3
+ LAYER_PROJECTION_MAX_ROWS,
4
+ LAYER_PROJECTION_MAX_TOP_K,
5
+ LAYER_PROJECTION_SCHEMA,
6
+ topCandidates,
7
+ } from '../inspection.js';
8
+
9
+ // Projects recorded layer outputs through the loaded model's final
10
+ // normalization and output head. The pipeline owns the computation; this
11
+ // validates the request, snapshots it and labels the result. The candidates are
12
+ // a projection of each vector: they are not tokens the model produced there.
13
+ /** @type {typeof import('./layer-projection.js').projectLayerOutputs} */
14
+ export const projectLayerOutputs = async function projectLayerOutputs(pipeline, modelId, request) {
15
+ const vectors = request?.vectors;
16
+ const topK = request?.topK;
17
+ if (!Array.isArray(vectors) || vectors.length === 0 || vectors.length > LAYER_PROJECTION_MAX_ROWS) {
18
+ throw new Error(`Doppler model.inspect.projectLayerOutputs requires 1 to ${LAYER_PROJECTION_MAX_ROWS} vectors.`);
19
+ }
20
+ if (!Number.isInteger(topK) || topK < 1 || topK > LAYER_PROJECTION_MAX_TOP_K) {
21
+ throw new Error(`Doppler model.inspect.projectLayerOutputs requires topK as a whole number from 1 to ${LAYER_PROJECTION_MAX_TOP_K}.`);
22
+ }
23
+ const width = vectors[0]?.length;
24
+ if (!Number.isInteger(width) || width < 1 || vectors.some((vector) => !(vector instanceof Float32Array) || vector.length !== width)) {
25
+ throw new Error('Doppler model.inspect.projectLayerOutputs requires Float32Array vectors of one length.');
26
+ }
27
+ // Snapshot caller-owned vectors before awaiting the pipeline's execution slot.
28
+ const requestedRows = vectors.length;
29
+ const hiddenStates = new Float32Array(requestedRows * width);
30
+ vectors.forEach((vector, row) => hiddenStates.set(vector, row * width));
31
+ return runPipelineOperation(pipeline, async (scoped) => {
32
+ if (typeof scoped.projectHiddenStates !== 'function') {
33
+ throw new Error('The loaded Doppler pipeline cannot project hidden states.');
34
+ }
35
+ const { logits, rowCount, vocabSize } = await scoped.projectHiddenStates(hiddenStates, requestedRows);
36
+ return {
37
+ schema: LAYER_PROJECTION_SCHEMA,
38
+ modelId,
39
+ projection: { through: ['final-normalization', 'output-head'], kind: 'projected' },
40
+ vocabSize,
41
+ rows: Array.from({ length: rowCount }, (_, row) => ({
42
+ candidates: topCandidates(logits.subarray(row * vocabSize, (row + 1) * vocabSize), scoped.tokenizer, topK),
43
+ })),
44
+ };
45
+ });
46
+ };
@@ -261,6 +261,18 @@ export interface DopplerModelHandle {
261
261
  }) => void;
262
262
  }
263
263
  ): Promise<DopplerModelInspectionReceipt>;
264
+ /**
265
+ * Projects hidden-state vectors (for example recorded `layer-output` frames)
266
+ * through this model's final normalization and output head, and returns the
267
+ * `topK` candidates per vector. The result is a projection, sometimes called
268
+ * a logit lens: an estimate of what each vector leans toward, not a token the
269
+ * model produced at that layer. Fails for hyper-connection models and for
270
+ * paired-precision execution plans. Does not change sequence state.
271
+ */
272
+ projectLayerOutputs(request: {
273
+ vectors: Float32Array[];
274
+ topK: number;
275
+ }): Promise<import('../inspection.js').DopplerLayerProjection>;
264
276
  };
265
277
  readonly advanced: {
266
278
  tokenizeText(text: string): number[];
@@ -24,6 +24,7 @@ import {
24
24
  listObservationPolicies,
25
25
  resolveObservationPolicy,
26
26
  } from '../inspection.js';
27
+ import { projectLayerOutputs } from './layer-projection.js';
27
28
  import {
28
29
  activateLoRAFromTrainingOutputForPipeline,
29
30
  activatePreparedLoRAForPipeline,
@@ -730,6 +731,9 @@ export function createModelHandle(pipeline, resolved) {
730
731
  }
731
732
  return receipt;
732
733
  },
734
+ projectLayerOutputs(request) {
735
+ return projectLayerOutputs(pipeline, resolved.modelId, request);
736
+ },
733
737
  };
734
738
 
735
739
  return handle;
@@ -31,6 +31,7 @@ export const PIPELINE_OPERATIONS = Object.freeze({
31
31
  advanceWithToken: 'execution', advanceWithTokenAndEmbedding: 'execution',
32
32
  prefillKVOnly: 'execution', prefillForLoRATraining: 'execution',
33
33
  computeDiffusionGemmaCanvasLogits: 'execution', computeDiffusionGemmaCanvasStep: 'execution',
34
+ projectHiddenStates: 'execution',
34
35
  prefillWithEmbedding: 'execution', prefillWithLogits: 'execution',
35
36
  prefillWithTokenLogits: 'execution', prefillWithTokenLogitsFromKV: 'execution',
36
37
  embed: 'execution', embedBatch: Object.freeze({ kind: 'execution', context: 'explicit' }), encodeSequence: 'execution',
@@ -0,0 +1,18 @@
1
+ import type { PipelineState } from '../state.js';
2
+
3
+ export interface HiddenProjectionResult {
4
+ /** Row-major logits: `rowCount` rows of `vocabSize` values. */
5
+ logits: Float32Array;
6
+ rowCount: number;
7
+ vocabSize: number;
8
+ }
9
+
10
+ /**
11
+ * Applies the model's final normalization and output head to caller-supplied
12
+ * hidden states. Fails for hyper-connection models and paired-precision plans.
13
+ */
14
+ export declare function projectHiddenStates(
15
+ state: PipelineState,
16
+ hiddenStates: Float32Array,
17
+ rowCount: number
18
+ ): Promise<HiddenProjectionResult>;
@@ -0,0 +1,49 @@
1
+ import { computeLogits } from '../logits/index.js';
2
+ import { getLogitsConfig, getLogitsWeights } from './logits-config.js';
3
+
4
+ // Projects caller-supplied hidden states through this model's own final
5
+ // normalization and output head: the computation every decode step ends with,
6
+ // applied to vectors that did not come from the last layer. The result is an
7
+ // observation aid (a "logit lens"), not something the model produced at that
8
+ // layer. Nothing here touches sequence state or the KV cache.
9
+ /** @type {typeof import('./hidden-projection.js').projectHiddenStates} */
10
+ export const projectHiddenStates = async function projectHiddenStates(state, hiddenStates, rowCount) {
11
+ if (!(hiddenStates instanceof Float32Array)) {
12
+ throw new Error('projectHiddenStates requires hidden states as a Float32Array.');
13
+ }
14
+ if (!Number.isInteger(rowCount) || rowCount < 1) {
15
+ throw new Error('projectHiddenStates requires a positive whole number of rows.');
16
+ }
17
+ const config = getLogitsConfig(state);
18
+ if (config.hyperConnections) {
19
+ // Their trace rows hold several streams and a mixer replaces the final norm.
20
+ throw new Error('projectHiddenStates does not support hyper-connection models: a recorded layer output there is not one hidden state.');
21
+ }
22
+ if (config.activationPrecision !== undefined && config.activationPrecision !== null) {
23
+ throw new Error(`projectHiddenStates requires single-component activations; the active plan uses "${config.activationPrecision}".`);
24
+ }
25
+ if (hiddenStates.length !== rowCount * config.hiddenSize) {
26
+ throw new Error(`projectHiddenStates expected ${rowCount} rows of ${config.hiddenSize} values (${rowCount * config.hiddenSize}), got ${hiddenStates.length}.`);
27
+ }
28
+ for (let index = 0; index < hiddenStates.length; index += 1) {
29
+ if (!Number.isFinite(hiddenStates[index])) {
30
+ throw new Error(`projectHiddenStates received a non-finite value at index ${index}.`);
31
+ }
32
+ }
33
+ const logits = await computeLogits(
34
+ hiddenStates,
35
+ rowCount,
36
+ getLogitsWeights(state),
37
+ config,
38
+ state.useGPU,
39
+ state.debugFlags,
40
+ undefined,
41
+ undefined,
42
+ state.runtimeConfig.shared.debug.probes,
43
+ { lastPositionOnly: false }
44
+ );
45
+ if (!(logits instanceof Float32Array) || logits.length % rowCount !== 0) {
46
+ throw new Error('projectHiddenStates did not receive one logit row per hidden state.');
47
+ }
48
+ return { logits, rowCount, vocabSize: logits.length / rowCount };
49
+ };
@@ -8,6 +8,7 @@ import { releaseBuffer } from '../../../memory/buffer-pool.js';
8
8
  import { sample, applyRepetitionPenalty, applyPresencePenalty } from './sampling.js';
9
9
  import { isStopToken } from './init.js';
10
10
  import { decodeStepLogits } from './generator-steps.js';
11
+ import { projectHiddenStates as projectHiddenStatesImpl } from './generator/hidden-projection.js';
11
12
  import { buildLayerContext, debugCheckBuffer as debugCheckBufferHelper } from './generator/session-context.js';
12
13
  import { getLogitsConfig, getLogitsWeights } from './generator/logits-config.js';
13
14
  import { releaseSharedAttentionState } from './generator/attention-lifecycle.js';
@@ -408,6 +409,10 @@ export class PipelineGenerator {
408
409
  return computeDiffusionGemmaCanvasLogitsImpl.apply(this, arguments);
409
410
  }
410
411
 
412
+ async projectHiddenStates(hiddenStates, rowCount) {
413
+ return projectHiddenStatesImpl(this._state, hiddenStates, rowCount);
414
+ }
415
+
411
416
  async computeDiffusionGemmaCanvasStep(args, options = {}) {
412
417
  return computeDiffusionGemmaCanvasStepImpl.apply(this, arguments);
413
418
  }
@@ -114,6 +114,14 @@ export declare class InferencePipeline extends PipelineState {
114
114
  options?: GenerateOptions & { __internalGenerate?: boolean }
115
115
  ): Promise<Float32Array>;
116
116
 
117
+ /**
118
+ * Applies the final normalization and output head to caller-supplied hidden
119
+ * states (`rowCount` rows of `hiddenSize`). An observation aid: the logits
120
+ * are a projection, not what the model produced at an earlier layer. Does
121
+ * not read or change sequence state.
122
+ */
123
+ projectHiddenStates(hiddenStates: Float32Array, rowCount: number): Promise<import('./generator/hidden-projection.js').HiddenProjectionResult>;
124
+
117
125
  computeDiffusionGemmaCanvasStep(
118
126
  args: DiffusionGemmaCanvasStepInput,
119
127
  options?: GenerateOptions & { __internalGenerate?: boolean }
@@ -301,6 +301,10 @@ export class InferencePipeline extends PipelineState {
301
301
  return this.generator.computeDiffusionGemmaCanvasLogits(args, options);
302
302
  }
303
303
 
304
+ projectHiddenStates(hiddenStates, rowCount) {
305
+ return this.generator.projectHiddenStates(hiddenStates, rowCount);
306
+ }
307
+
304
308
  computeDiffusionGemmaCanvasStep(args, options = {}) {
305
309
  assertNotAborted(options?.signal);
306
310
  return this.generator.computeDiffusionGemmaCanvasStep(args, options);
package/src/version.js CHANGED
@@ -1,2 +1,2 @@
1
- export const DOPPLER_VERSION = '0.7.1';
1
+ export const DOPPLER_VERSION = '0.7.3';
2
2
  export const DOPPLER_PROVIDER_VERSION = DOPPLER_VERSION;