doppler-gpu 0.4.14 → 0.5.1

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.
Files changed (222) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +83 -52
  3. package/package.json +25 -2
  4. package/src/cli/doppler-cli.js +253 -94
  5. package/src/cli/runtime-profiles.js +3 -7
  6. package/src/client/doppler-api.d.ts +28 -0
  7. package/src/client/doppler-api.js +2 -0
  8. package/src/client/inspection.d.ts +122 -0
  9. package/src/client/inspection.js +343 -0
  10. package/src/client/runtime/index.d.ts +54 -0
  11. package/src/client/runtime/index.js +190 -18
  12. package/src/client/runtime/model-manager.d.ts +0 -4
  13. package/src/client/runtime/model-manager.js +0 -28
  14. package/src/client/runtime/model-session.d.ts +116 -1
  15. package/src/client/runtime/model-session.js +351 -1
  16. package/src/client/runtime/model-source.d.ts +10 -1
  17. package/src/client/runtime/scoped-session.d.ts +117 -0
  18. package/src/client/runtime/scoped-session.js +257 -0
  19. package/src/client/runtime/types.d.ts +0 -1
  20. package/src/client/runtime/types.js +0 -1
  21. package/src/config/evidence/boundary-evidence-policy.json +54 -0
  22. package/src/config/evidence/source-intake-policy.json +122 -0
  23. package/src/config/inspection/observation-policies.json +80 -0
  24. package/src/config/param-validator.js +21 -36
  25. package/src/config/runtime/compute/f16-activations.json +1 -0
  26. package/src/config/runtime/compute/f16-batched.json +1 -0
  27. package/src/config/runtime/default.json +1 -0
  28. package/src/config/runtime/diagnostics/debug-logits.json +1 -0
  29. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-alt.json +1 -0
  30. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-batched.json +1 -0
  31. package/src/config/runtime/experiments/bench/gemma3-bench-q4k.json +1 -0
  32. package/src/config/runtime/experiments/bench/gemma4-bench-q4k.json +1 -0
  33. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-alt.json +1 -0
  34. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-batched.json +1 -0
  35. package/src/config/runtime/experiments/debug/gemma3-browser-diagnose-q4k.json +1 -1
  36. package/src/config/runtime/experiments/debug/gemma3-debug-q4k.json +1 -3
  37. package/src/config/runtime/experiments/debug/gemma4-e2b-browser-diagnose-q4k.json +1 -1
  38. package/src/config/runtime/experiments/debug/qwen35-browser-diagnose-q4k.json +1 -1
  39. package/src/config/runtime/experiments/verify/gemma3-verify.json +1 -3
  40. package/src/config/runtime/experiments/verify/gemma4-e2b-verify.json +1 -3
  41. package/src/config/runtime/experiments/verify/lfm2-verify.json +1 -3
  42. package/src/config/runtime/experiments/verify/translategemma-verify.json +1 -3
  43. package/src/config/runtime/model/gemma2-debug.json +1 -0
  44. package/src/config/runtime/model/gemma2-pipeline-debug.json +1 -0
  45. package/src/config/runtime/model/gemma2-pipeline.json +1 -0
  46. package/src/config/runtime/model/gemma3-layer-probe.json +1 -0
  47. package/src/config/runtime/model/qwen3-5-layer-probe.json +1 -0
  48. package/src/config/runtime/model/qwen3-5-layer3-boundary-probe.json +1 -0
  49. package/src/config/runtime/model/qwen3-5-linear-attn-debug.json +1 -0
  50. package/src/config/runtime/optimization-candidates/registry.json +5 -0
  51. package/src/config/runtime/platform/metal-apple-q4k.json +1 -0
  52. package/src/config/runtime/profiles/default.json +1 -0
  53. package/src/config/runtime/profiles/diffusiongemma-26b-a4b-throughput.json +1 -0
  54. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-overlapped-probe.json +1 -0
  55. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-probe.json +1 -0
  56. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-b4.json +1 -3
  57. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-single.json +1 -3
  58. package/src/config/runtime/profiles/gemma4-31b-f16-activations-probe.json +1 -5
  59. package/src/config/runtime/profiles/gemma4-e2b-baseline-probe.json +1 -3
  60. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-probe.json +1 -3
  61. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-test.json +1 -0
  62. package/src/config/runtime/profiles/gemma4-e2b-int4ple-baseline-probe.json +1 -5
  63. package/src/config/runtime/profiles/gemma4-e2b-int4ple-f16a-probe.json +1 -5
  64. package/src/config/runtime/profiles/gemma4-e2b-int4ple-reference-export.json +1 -3
  65. package/src/config/runtime/profiles/gemma4-e2b-int4ple-retain-q4k-probe.json +1 -5
  66. package/src/config/runtime/profiles/gemma4-e2b-low-memory.json +1 -0
  67. package/src/config/runtime/profiles/gemma4-e2b-prefill-profile.json +1 -3
  68. package/src/config/runtime/profiles/gemma4-e2b-throughput-probe.json +1 -0
  69. package/src/config/runtime/profiles/low-memory.json +1 -0
  70. package/src/config/runtime/profiles/production.json +1 -3
  71. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-attn128-candidate.json +1 -0
  72. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-maxbatch64-candidate.json +1 -0
  73. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-normed-ffn-candidate.json +1 -0
  74. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-overlap-ringtokens1-candidate.json +1 -0
  75. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-parity.json +1 -0
  76. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-sequential-candidate.json +1 -0
  77. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-throughput.json +1 -0
  78. package/src/config/runtime/profiles/qwen-3-5-0-8b-prefill-profile.json +1 -3
  79. package/src/config/runtime/profiles/qwen-3-5-0-8b-throughput-probe.json +1 -0
  80. package/src/config/runtime/profiles/qwen-3-5-2b-f16-primary-throughput.json +1 -5
  81. package/src/config/runtime/profiles/qwen-3-5-2b-metal-parity.json +1 -0
  82. package/src/config/runtime/profiles/qwen-3-5-2b-metal-throughput.json +1 -0
  83. package/src/config/runtime/profiles/qwen-3-5-9b-metal-correctness.json +1 -0
  84. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-stability.json +1 -3
  85. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-throughput.json +1 -0
  86. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-stability.json +1 -0
  87. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-throughput.json +1 -0
  88. package/src/config/runtime/profiles/qwen3-6-27b-f16-activations-probe.json +1 -5
  89. package/src/config/runtime/profiles/rerank-stability.json +1 -3
  90. package/src/config/runtime/profiles/rerank-throughput.json +1 -3
  91. package/src/config/runtime/profiles/simulation.json +1 -3
  92. package/src/config/runtime/profiles/throughput.json +1 -3
  93. package/src/config/runtime/profiles/trace-layers.json +1 -3
  94. package/src/config/runtime/profiles/translategemma-1b-nativekd2-q4k-rdna3-throughput-probe.json +1 -0
  95. package/src/config/runtime/profiles/turboquant-contiguous-prod.json +1 -0
  96. package/src/config/runtime/profiles/turboquant-contiguous.json +1 -0
  97. package/src/config/runtime/profiles/turboquant.json +1 -0
  98. package/src/config/runtime/profiles/vector-stability.json +1 -3
  99. package/src/config/runtime/profiles/vector-throughput.json +1 -0
  100. package/src/config/runtime/profiles/verbose-trace.json +1 -3
  101. package/src/config/runtime/tiers/gemma4-128gb.json +1 -0
  102. package/src/config/runtime/tiers/gemma4-16gb.json +1 -0
  103. package/src/config/runtime/tiers/gemma4-24gb.json +1 -0
  104. package/src/config/runtime/tiers/gemma4-32gb.json +1 -0
  105. package/src/config/schema/benchmark.schema.d.ts +7 -0
  106. package/src/config/schema/benchmark.schema.js +5 -0
  107. package/src/config/schema/index.d.ts +8 -16
  108. package/src/config/schema/index.js +5 -8
  109. package/src/config/schema/kernel-thresholds.schema.d.ts +0 -12
  110. package/src/config/schema/kernel-thresholds.schema.js +0 -12
  111. package/src/config/schema/kernel-warmup.schema.d.ts +1 -3
  112. package/src/config/schema/kernel-warmup.schema.js +0 -1
  113. package/src/config/schema/runtime-profile.schema.d.ts +24 -0
  114. package/src/config/schema/runtime-profile.schema.js +92 -0
  115. package/src/config/schema/shared-runtime.schema.d.ts +1 -4
  116. package/src/config/schema/shared-runtime.schema.js +0 -2
  117. package/src/config/schema/tooling.schema.d.ts +8 -5
  118. package/src/config/schema/tooling.schema.js +3 -2
  119. package/src/debug/tensor.d.ts +2 -0
  120. package/src/debug/tensor.js +21 -2
  121. package/src/gpu/command-recorder.d.ts +5 -0
  122. package/src/gpu/command-recorder.js +17 -0
  123. package/src/gpu/kernel-runtime.js +2 -10
  124. package/src/gpu/kernels/index.d.ts +0 -2
  125. package/src/gpu/kernels/index.js +0 -2
  126. package/src/gpu/kernels/kernel-prewarm.d.ts +3 -0
  127. package/src/gpu/kernels/kernel-prewarm.js +60 -0
  128. package/src/gpu/kernels/utils.d.ts +2 -4
  129. package/src/gpu/kernels/utils.js +2 -4
  130. package/src/index.d.ts +13 -1
  131. package/src/index.js +7 -1
  132. package/src/inference/browser-harness-model-helpers.js +4 -0
  133. package/src/inference/browser-harness-runtime-helpers.js +25 -10
  134. package/src/inference/browser-harness-text-helpers.js +4 -1
  135. package/src/inference/browser-harness.d.ts +4 -0
  136. package/src/inference/browser-harness.js +91 -4
  137. package/src/inference/observation-context.d.ts +22 -0
  138. package/src/inference/observation-context.js +41 -0
  139. package/src/inference/pipelines/text/attention/attn-config.js +1 -1
  140. package/src/inference/pipelines/text/attention/executor-immediate.js +42 -0
  141. package/src/inference/pipelines/text/attention/executor-recorded.js +29 -0
  142. package/src/inference/pipelines/text/attention/index.js +7 -0
  143. package/src/inference/pipelines/text/attention/interpreter.js +1334 -0
  144. package/src/inference/pipelines/text/attention/plan.d.ts +36 -0
  145. package/src/inference/pipelines/text/attention/plan.js +328 -0
  146. package/src/inference/pipelines/text/attention/receipt.js +60 -0
  147. package/src/inference/pipelines/text/attention/record.js +8 -1278
  148. package/src/inference/pipelines/text/attention/run.js +8 -1386
  149. package/src/inference/pipelines/text/generator-decode-policy.js +4 -1
  150. package/src/inference/pipelines/text/generator-helpers.js +2 -0
  151. package/src/inference/pipelines/text/generator-steps.js +32 -15
  152. package/src/inference/pipelines/text/generator.js +10 -5
  153. package/src/inference/pipelines/text/init.d.ts +3 -0
  154. package/src/inference/pipelines/text/layer-plan-gpu.js +2 -0
  155. package/src/inference/pipelines/text/layer.js +2 -0
  156. package/src/inference/pipelines/text/model-load.d.ts +0 -1
  157. package/src/inference/pipelines/text/model-load.js +2 -11
  158. package/src/inference/pipelines/text/probes.js +10 -0
  159. package/src/inference/pipelines/text/resolved-runtime-session.d.ts +56 -0
  160. package/src/inference/pipelines/text/resolved-runtime-session.js +175 -0
  161. package/src/inference/pipelines/text/state.d.ts +6 -0
  162. package/src/inference/pipelines/text/state.js +3 -0
  163. package/src/inference/pipelines/text/types.d.ts +6 -0
  164. package/src/inference/pipelines/text.js +16 -1
  165. package/src/inference/refactor-receipt.d.ts +49 -0
  166. package/src/inference/refactor-receipt.js +188 -0
  167. package/src/inference/resource-scope.d.ts +33 -0
  168. package/src/inference/resource-scope.js +168 -0
  169. package/src/inference/test-harness.d.ts +3 -0
  170. package/src/inference/test-harness.js +1 -0
  171. package/src/storage/model-cache.d.ts +53 -0
  172. package/src/storage/model-cache.js +550 -0
  173. package/src/tooling/boundary-evidence.d.ts +51 -0
  174. package/src/tooling/boundary-evidence.js +408 -0
  175. package/src/tooling/browser-command-runner.js +4 -4
  176. package/src/tooling/command-context.d.ts +25 -0
  177. package/src/tooling/command-context.js +53 -0
  178. package/src/tooling/command-runner-shared.js +22 -5
  179. package/src/tooling/demo-receipts.d.ts +56 -0
  180. package/src/tooling/demo-receipts.js +113 -0
  181. package/src/tooling/diagnose-runner.js +2 -2
  182. package/src/tooling/execution-cost-ledger.d.ts +21 -0
  183. package/src/tooling/execution-cost-ledger.js +199 -0
  184. package/src/tooling/node-command-runner.js +2 -2
  185. package/src/tooling/opfs-cache.d.ts +11 -49
  186. package/src/tooling/opfs-cache.js +4 -510
  187. package/src/tooling/precision-replay-math.d.ts +42 -0
  188. package/src/tooling/precision-replay-math.js +174 -0
  189. package/src/tooling/program-bundle-parity.d.ts +3 -0
  190. package/src/tooling/program-bundle-parity.js +8 -0
  191. package/src/tooling/program-bundle.d.ts +1 -52
  192. package/src/tooling/program-bundle.js +0 -139
  193. package/src/tooling/registered-variant-calibration.d.ts +24 -0
  194. package/src/tooling/registered-variant-calibration.js +286 -0
  195. package/src/tooling/runtime-input-composition.js +105 -53
  196. package/src/tooling/runtime-intent.js +41 -0
  197. package/src/tooling/runtime-optimization-index.d.ts +6 -0
  198. package/src/tooling/runtime-optimization-index.js +72 -0
  199. package/src/tooling/runtime-optimization.d.ts +47 -6
  200. package/src/tooling/runtime-optimization.js +559 -40
  201. package/src/tooling/source-intake.d.ts +49 -0
  202. package/src/tooling/source-intake.js +414 -0
  203. package/src/tooling-exports/evidence.d.ts +34 -0
  204. package/src/tooling-exports/evidence.js +34 -0
  205. package/src/tooling-exports/runtime.d.ts +7 -0
  206. package/src/tooling-exports/runtime.js +7 -0
  207. package/src/tooling-exports.d.ts +11 -0
  208. package/src/tooling-exports.js +6 -3
  209. package/src/tooling-exports.shared.d.ts +32 -0
  210. package/src/tooling-exports.shared.js +31 -0
  211. package/src/version.js +1 -1
  212. package/src/config/schema/tuner.schema.d.ts +0 -39
  213. package/src/config/schema/tuner.schema.js +0 -13
  214. package/src/gpu/kernel-tuner/benchmarks.js +0 -902
  215. package/src/gpu/kernel-tuner/cache.js +0 -145
  216. package/src/gpu/kernel-tuner/index.js +0 -38
  217. package/src/gpu/kernel-tuner/tuner.js +0 -247
  218. package/src/gpu/kernel-tuner.js +0 -12
  219. package/src/gpu/kernels/kernel-tuning.d.ts +0 -42
  220. package/src/gpu/kernels/kernel-tuning.js +0 -158
  221. package/src/gpu/profiler.js +0 -382
  222. package/src/inference/pipelines/text/attention/output-gate-fusion.js +0 -37
@@ -1,5 +1,16 @@
1
1
  import { getKernelCapabilities } from '../../gpu/device.js';
2
2
  import { formatChatMessages } from '../../inference/pipelines/text/chat-format.js';
3
+ import { resolveSamplingConfig } from '../../inference/pipelines/text/sampling-config.js';
4
+ import { DOPPLER_VERSION } from '../../version.js';
5
+ import { isNodeRuntime } from '../../utils/runtime-env.js';
6
+ import {
7
+ MODEL_INSPECTION_RECEIPT_SCHEMA,
8
+ aggregateWordPerplexity,
9
+ buildComparisonFingerprint,
10
+ buildInspectionTokenRecords,
11
+ listObservationPolicies,
12
+ resolveObservationPolicy,
13
+ } from '../inspection.js';
3
14
  import {
4
15
  activateLoRAFromTrainingOutputForPipeline,
5
16
  getActiveLoRAForPipeline,
@@ -58,8 +69,274 @@ async function collectText(iterable) {
58
69
  return output;
59
70
  }
60
71
 
61
- export function createModelHandle(pipeline, resolved) {
72
+ const GENERATION_EVIDENCE_SCHEMA = 'doppler_generation_evidence/v1';
73
+ const GENERATION_TRANSCRIPT_SCHEMA = 'doppler_generation_transcript/v1';
74
+ const RUNTIME_PROFILE_SCHEMA = 'doppler_runtime_profile/v1';
75
+
76
+ function canonicalizeEvidence(value) {
77
+ if (value === null || typeof value === 'boolean' || typeof value === 'string') {
78
+ return JSON.stringify(value);
79
+ }
80
+ if (typeof value === 'number') {
81
+ if (!Number.isFinite(value)) {
82
+ throw new Error('Doppler generation evidence cannot hash non-finite numbers.');
83
+ }
84
+ return JSON.stringify(value);
85
+ }
86
+ if (Array.isArray(value)) {
87
+ return `[${value.map((entry) => canonicalizeEvidence(entry)).join(',')}]`;
88
+ }
89
+ if (value && typeof value === 'object') {
90
+ const entries = Object.keys(value)
91
+ .sort()
92
+ .map((key) => `${JSON.stringify(key)}:${canonicalizeEvidence(value[key])}`);
93
+ return `{${entries.join(',')}}`;
94
+ }
95
+ throw new Error(`Doppler generation evidence cannot hash ${typeof value} values.`);
96
+ }
97
+
98
+ function bytesToHex(bytes) {
99
+ return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
100
+ }
101
+
102
+ async function hashEvidenceValue(value) {
103
+ if (!globalThis.crypto?.subtle) {
104
+ throw new Error('Doppler generation evidence requires Web Crypto SHA-256 support.');
105
+ }
106
+ const bytes = new TextEncoder().encode(canonicalizeEvidence(value));
107
+ const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
108
+ return `sha256:${bytesToHex(new Uint8Array(digest))}`;
109
+ }
110
+
111
+ function cleanEvidenceString(value) {
112
+ const text = String(value ?? '').trim();
113
+ return text || null;
114
+ }
115
+
116
+ function buildAdapterIdentity(deviceInfo = {}) {
117
+ return {
118
+ vendor: cleanEvidenceString(deviceInfo.vendor),
119
+ architecture: cleanEvidenceString(deviceInfo.architecture),
120
+ device: cleanEvidenceString(deviceInfo.device),
121
+ description: cleanEvidenceString(deviceInfo.description),
122
+ };
123
+ }
124
+
125
+ function buildGenerationBackendIdentity({
126
+ deviceInfo = null,
127
+ kernelCapabilities = null,
128
+ stats = null,
129
+ } = {}) {
130
+ const capabilities = kernelCapabilities && typeof kernelCapabilities === 'object'
131
+ ? kernelCapabilities
132
+ : {};
133
+ const adapter = deviceInfo && typeof deviceInfo === 'object'
134
+ ? deviceInfo
135
+ : (capabilities.adapterInfo || {});
136
+ const executionPlan = stats?.executionPlan || null;
137
+ const finalPlanId = executionPlan?.finalActivePlanId
138
+ || executionPlan?.activePlanIdAtStart
139
+ || null;
140
+ const primaryPlan = executionPlan?.primary || null;
141
+ const fallbackPlan = executionPlan?.fallback || null;
142
+ const finalPlan = finalPlanId && fallbackPlan?.id === finalPlanId
143
+ ? fallbackPlan
144
+ : primaryPlan;
145
+ return {
146
+ backend: 'webgpu',
147
+ adapter: buildAdapterIdentity(adapter),
148
+ hasF16: capabilities.hasF16 === true,
149
+ hasSubgroups: capabilities.hasSubgroups === true,
150
+ maxBufferSize: Number(capabilities.maxBufferSize || 0),
151
+ deviceEpoch: Number(capabilities.deviceEpoch || 0),
152
+ kernelPathId: cleanEvidenceString(stats?.kernelPathId || finalPlan?.kernelPathId),
153
+ kernelPathSource: cleanEvidenceString(stats?.kernelPathSource || finalPlan?.kernelPathSource),
154
+ executionPlanId: cleanEvidenceString(finalPlanId),
155
+ activationDtype: cleanEvidenceString(finalPlan?.activationDtype),
156
+ };
157
+ }
158
+
159
+ async function buildGenerationEvidence({
160
+ outputText,
161
+ tokenIds,
162
+ generationConfig,
163
+ modelId,
164
+ manifestHash,
165
+ activeAdapter,
166
+ backendIdentity,
167
+ stats,
168
+ } = {}) {
169
+ if (typeof outputText !== 'string') {
170
+ throw new Error('Doppler generation evidence requires outputText.');
171
+ }
172
+ if (!Array.isArray(tokenIds) || tokenIds.some((tokenId) => !Number.isInteger(tokenId) || tokenId < 0)) {
173
+ throw new Error('Doppler generation evidence requires non-negative integer tokenIds.');
174
+ }
175
+ const transcript = {
176
+ schema: GENERATION_TRANSCRIPT_SCHEMA,
177
+ outputText,
178
+ tokenIds: [...tokenIds],
179
+ };
180
+ const generationConfigHash = await hashEvidenceValue(generationConfig);
181
+ const transcriptHash = await hashEvidenceValue(transcript);
182
+ const backendIdentityHash = await hashEvidenceValue(backendIdentity);
183
+ const runtimeProfile = {
184
+ schema: RUNTIME_PROFILE_SCHEMA,
185
+ runtime: {
186
+ package: 'doppler-gpu',
187
+ version: DOPPLER_VERSION,
188
+ surface: isNodeRuntime() ? 'node' : 'browser',
189
+ },
190
+ model: {
191
+ modelId: cleanEvidenceString(modelId),
192
+ manifestHash: cleanEvidenceString(manifestHash),
193
+ activeAdapter: cleanEvidenceString(activeAdapter),
194
+ },
195
+ backendIdentity,
196
+ };
197
+ const runtimeProfileHash = await hashEvidenceValue(runtimeProfile);
198
+ return {
199
+ schema: GENERATION_EVIDENCE_SCHEMA,
200
+ outputText,
201
+ tokenIds: [...tokenIds],
202
+ transcript,
203
+ transcriptHash,
204
+ generationConfig,
205
+ generationConfigHash,
206
+ runtimeProfile,
207
+ runtimeProfileHash,
208
+ backendIdentity,
209
+ backendIdentityHash,
210
+ stats: stats && typeof stats === 'object' ? stats : null,
211
+ };
212
+ }
213
+
214
+ function resolveUseChatTemplate(pipeline, options) {
215
+ if (typeof options.useChatTemplate === 'boolean') {
216
+ return options.useChatTemplate;
217
+ }
218
+ const runtimeValue = pipeline?.runtimeConfig?.inference?.chatTemplate?.enabled;
219
+ if (typeof runtimeValue === 'boolean') {
220
+ return runtimeValue;
221
+ }
222
+ const modelValue = pipeline?.modelConfig?.chatTemplateEnabled;
223
+ return typeof modelValue === 'boolean' ? modelValue : false;
224
+ }
225
+
226
+ function resolveGenerationConfigEvidence(pipeline, options) {
227
+ const runtimeConfig = pipeline?.runtimeConfig;
228
+ const generation = runtimeConfig?.inference?.generation;
229
+ if (!generation || typeof generation !== 'object' || Array.isArray(generation)) {
230
+ throw new Error('Loaded Doppler pipeline does not expose resolved generation config.');
231
+ }
232
+ const maxTokens = options.maxTokens ?? generation.maxTokens;
233
+ if (!Number.isInteger(maxTokens) || maxTokens <= 0) {
234
+ throw new Error('Resolved Doppler generation maxTokens must be a positive integer.');
235
+ }
236
+ const sampling = resolveSamplingConfig(options, runtimeConfig);
237
+ const stopSequences = options.stopSequences ?? [];
238
+ if (!Array.isArray(stopSequences) || stopSequences.some((value) => typeof value !== 'string')) {
239
+ throw new Error('Resolved Doppler stopSequences must be an array of strings.');
240
+ }
241
+ const useSpeculative = options.useSpeculative ?? generation.useSpeculative ?? null;
242
+ if (useSpeculative !== null && typeof useSpeculative !== 'boolean') {
243
+ throw new Error('Resolved Doppler useSpeculative must be a boolean or null.');
244
+ }
245
+ const seed = options.seed ?? null;
246
+ if (seed !== null && (!Number.isFinite(seed) || seed < 0)) {
247
+ throw new Error('Resolved Doppler seed must be null or a non-negative number.');
248
+ }
62
249
  return {
250
+ maxTokens,
251
+ temperature: sampling.temperature,
252
+ topP: sampling.topP,
253
+ topK: sampling.topK,
254
+ repetitionPenalty: sampling.repetitionPenalty,
255
+ repetitionPenaltyWindow: sampling.repetitionPenaltyWindow,
256
+ greedyThreshold: sampling.greedyThreshold,
257
+ suppressSpecialTokens: sampling.suppressSpecialTokens,
258
+ suppressSpecialLikeTokens: sampling.suppressSpecialLikeTokens,
259
+ suppressTokenIds: [...sampling.suppressTokenIds],
260
+ stopSequences: [...stopSequences],
261
+ useChatTemplate: resolveUseChatTemplate(pipeline, options),
262
+ useSpeculative,
263
+ seed,
264
+ };
265
+ }
266
+
267
+ function decodeGeneratedTokens(pipeline, tokenIds) {
268
+ if (!pipeline?.tokenizer || typeof pipeline.tokenizer.decode !== 'function') {
269
+ throw new Error('Loaded Doppler pipeline does not expose tokenizer.decode().');
270
+ }
271
+ return String(pipeline.tokenizer.decode(tokenIds, true, false));
272
+ }
273
+
274
+ function resolveInspectionBrowserIdentity() {
275
+ const navigatorValue = globalThis.navigator;
276
+ return {
277
+ userAgent: navigatorValue?.userAgent ?? '',
278
+ platform: navigatorValue?.platform ?? '',
279
+ language: navigatorValue?.language ?? '',
280
+ };
281
+ }
282
+
283
+ function resolveTokenizerContract(pipeline) {
284
+ const contract = pipeline?.manifest?.tokenizer;
285
+ if (!contract || typeof contract !== 'object' || Array.isArray(contract)) {
286
+ throw new Error('Loaded Doppler manifest does not expose tokenizer identity.');
287
+ }
288
+ return contract;
289
+ }
290
+
291
+ function resolveInspectionGenerationOptions(options, policy) {
292
+ const generation = options?.generation ?? {};
293
+ if (!generation || typeof generation !== 'object' || Array.isArray(generation)) {
294
+ throw new Error('Doppler inspection generation options must be an object.');
295
+ }
296
+ for (const field of ['onToken', 'onLogits', 'profile', 'disableCommandBatching']) {
297
+ if (Object.prototype.hasOwnProperty.call(generation, field)) {
298
+ throw new Error(`Doppler inspection owns generation.${field} through its observation policy.`);
299
+ }
300
+ }
301
+ const resolved = { ...generation };
302
+ if (policy.modifiesExecution) {
303
+ resolved.disableCommandBatching = true;
304
+ }
305
+ if (policy.gpuTimestampQueries) {
306
+ resolved.profile = true;
307
+ }
308
+ return resolved;
309
+ }
310
+
311
+ export function createModelHandle(pipeline, resolved) {
312
+ async function generateWithEvidence(prompt, options = {}) {
313
+ assertSupportedGenerationOptions(options);
314
+ const generationConfig = resolveGenerationConfigEvidence(pipeline, options);
315
+ const result = await pipeline.generateTokenIds(prompt, options);
316
+ const tokenIds = Array.from(result?.tokenIds || [], Number);
317
+ const outputText = decodeGeneratedTokens(pipeline, tokenIds);
318
+ const stats = result?.stats || pipeline.getStats?.() || null;
319
+ const kernelCapabilities = typeof pipeline.getKernelCapabilities === 'function'
320
+ ? pipeline.getKernelCapabilities()
321
+ : getKernelCapabilities();
322
+ const backendIdentity = buildGenerationBackendIdentity({
323
+ deviceInfo: kernelCapabilities?.adapterInfo || null,
324
+ kernelCapabilities,
325
+ stats,
326
+ });
327
+ return buildGenerationEvidence({
328
+ outputText,
329
+ tokenIds,
330
+ generationConfig,
331
+ modelId: resolved.modelId,
332
+ manifestHash: resolved.manifestHash || null,
333
+ activeAdapter: getActiveLoRAForPipeline(pipeline),
334
+ backendIdentity,
335
+ stats,
336
+ });
337
+ }
338
+
339
+ const handle = {
63
340
  generate(prompt, options = {}) {
64
341
  assertSupportedGenerationOptions(options);
65
342
  return pipeline.generate(prompt, options);
@@ -68,6 +345,7 @@ export function createModelHandle(pipeline, resolved) {
68
345
  assertSupportedGenerationOptions(options);
69
346
  return collectText(pipeline.generate(prompt, options));
70
347
  },
348
+ generateWithEvidence,
71
349
  chat(messages, options = {}) {
72
350
  assertSupportedGenerationOptions(options);
73
351
  return pipeline.generate(messages, options);
@@ -159,6 +437,9 @@ export function createModelHandle(pipeline, resolved) {
159
437
  get manifestHash() {
160
438
  return resolved.manifestHash || null;
161
439
  },
440
+ get persistentCache() {
441
+ return resolved.persistentCache || null;
442
+ },
162
443
  get manifest() {
163
444
  return pipeline.manifest;
164
445
  },
@@ -198,4 +479,73 @@ export function createModelHandle(pipeline, resolved) {
198
479
  },
199
480
  },
200
481
  };
482
+
483
+ handle.inspect = {
484
+ listPolicies() {
485
+ return listObservationPolicies();
486
+ },
487
+ async generate(prompt, options = {}) {
488
+ if (typeof prompt !== 'string' || !prompt.trim()) {
489
+ throw new Error('Doppler model.inspect.generate requires a non-empty string prompt.');
490
+ }
491
+ const policy = resolveObservationPolicy(options.policyId);
492
+ const generationOptions = resolveInspectionGenerationOptions(options, policy);
493
+ assertSupportedGenerationOptions(generationOptions);
494
+ const logitsByStep = [];
495
+ if (policy.requiredCaptures.includes('selected-token-probabilities')) {
496
+ generationOptions.onLogits = (logits) => {
497
+ logitsByStep.push(Float32Array.from(logits));
498
+ };
499
+ }
500
+ const startedAt = performance.now();
501
+ const evidence = await generateWithEvidence(prompt, generationOptions);
502
+ const completedAt = performance.now();
503
+ const promptTokenIds = tokenizeText(pipeline, prompt);
504
+ const tokenRecords = policy.perplexity
505
+ ? buildInspectionTokenRecords(
506
+ evidence.tokenIds,
507
+ logitsByStep,
508
+ pipeline.tokenizer,
509
+ Number.isInteger(options.topKSize) ? options.topKSize : 5
510
+ )
511
+ : [];
512
+ const quality = policy.perplexity
513
+ ? aggregateWordPerplexity(tokenRecords, {
514
+ windowUnit: policy.perplexity.rollingWindow.unit,
515
+ windowSize: policy.perplexity.rollingWindow.size,
516
+ })
517
+ : null;
518
+ const fingerprint = buildComparisonFingerprint({
519
+ artifact: {
520
+ modelId: resolved.modelId,
521
+ manifestHash: resolved.manifestHash,
522
+ },
523
+ tokenizer: resolveTokenizerContract(pipeline),
524
+ promptTokenIds,
525
+ sampling: evidence.generationConfig,
526
+ observationPolicyId: policy.id,
527
+ execution: evidence.backendIdentity,
528
+ browser: resolveInspectionBrowserIdentity(),
529
+ adapter: evidence.backendIdentity.adapter,
530
+ });
531
+ const receipt = {
532
+ schema: MODEL_INSPECTION_RECEIPT_SCHEMA,
533
+ policy,
534
+ fingerprint,
535
+ outputText: evidence.outputText,
536
+ generatedTokenIds: [...evidence.tokenIds],
537
+ wallTimingMs: completedAt - startedAt,
538
+ performanceRepresentative: policy.performanceRepresentative,
539
+ tokens: tokenRecords,
540
+ quality,
541
+ generationEvidence: evidence,
542
+ };
543
+ if (typeof options.onEvent === 'function') {
544
+ options.onEvent({ type: 'inspection-complete', receipt });
545
+ }
546
+ return receipt;
547
+ },
548
+ };
549
+
550
+ return handle;
201
551
  }
@@ -2,11 +2,19 @@ import type { RDRRManifest } from '../../formats/rdrr/index.js';
2
2
  import type { SourceStorageContext } from '../../tooling/source-runtime-bundle.js';
3
3
 
4
4
  export interface DopplerLoadProgress {
5
- phase: 'resolve' | 'manifest' | 'load' | 'ready';
5
+ phase: 'resolve' | 'manifest' | 'cache' | 'load' | 'ready';
6
6
  percent: number;
7
7
  message: string;
8
8
  }
9
9
 
10
+ export interface DopplerPersistentCacheReceipt {
11
+ backend: 'opfs';
12
+ state: 'hit' | 'verified-hit' | 'manifest-refresh' | 'imported';
13
+ fromCache: boolean;
14
+ manifestHash: string;
15
+ totalBytes: number;
16
+ }
17
+
10
18
  export interface DopplerModelSourceResolution {
11
19
  modelId: string;
12
20
  baseUrl: string | null;
@@ -46,6 +54,7 @@ export interface DopplerLoadOptions {
46
54
  onProgress?: (event: DopplerLoadProgress) => void;
47
55
  runtimeConfig?: Record<string, unknown>;
48
56
  isolatedLoader?: boolean;
57
+ cache?: false | 'opfs';
49
58
  }
50
59
 
51
60
  export declare function createDefaultNodeLoadProgressLogger(): (event: DopplerLoadProgress) => void;
@@ -0,0 +1,117 @@
1
+ import type { ChatMessage } from '../../inference/pipelines/text/chat-format.js';
2
+ import type { SequenceEncodeOptions, SequenceEncodeResult } from '../../inference/pipelines/text/types.d.ts';
3
+ import type {
4
+ DopplerGenerateOptions,
5
+ DopplerGenerationEvidence,
6
+ DopplerModelHandle,
7
+ DopplerModelInspectionReceipt,
8
+ } from './model-session.js';
9
+ import type { DopplerPersistentCacheReceipt } from './model-source.js';
10
+
11
+ export type DopplerPromptInput = string | ChatMessage[] | { messages: ChatMessage[] };
12
+ export type DopplerCapability =
13
+ | 'generate'
14
+ | 'stream'
15
+ | 'embed'
16
+ | 'sequence'
17
+ | 'inspect'
18
+ | 'lora'
19
+ | 'advanced';
20
+ export type DopplerObservationTier = 'always' | 'guided-quality' | 'deep-xray';
21
+ export type DopplerObservationPolicyId =
22
+ | 'demo/always-on'
23
+ | 'demo/guided-quality'
24
+ | 'demo/deep-xray';
25
+
26
+ export interface DopplerScopedGenerateOptions extends DopplerGenerateOptions {
27
+ observe?: DopplerObservationTier | DopplerObservationPolicyId;
28
+ observationPolicy?: DopplerObservationTier | DopplerObservationPolicyId;
29
+ }
30
+
31
+ export interface DopplerGenerationResult {
32
+ schema: 'doppler.generation-result/v1';
33
+ outputText: string;
34
+ content: string;
35
+ tokenIds: number[];
36
+ usage: {
37
+ promptTokens: number | null;
38
+ completionTokens: number;
39
+ totalTokens: number | null;
40
+ };
41
+ observation: {
42
+ policyId: DopplerObservationPolicyId;
43
+ tier: DopplerObservationTier;
44
+ executionClassification: 'representative' | 'observed' | 'deep-diagnostic';
45
+ executionChanged: boolean;
46
+ unavailable: string[];
47
+ deepEvidenceAvailable: boolean | null;
48
+ };
49
+ fingerprint: {
50
+ modelId: string | null;
51
+ manifestHash: string | null;
52
+ tokenizerHash: string | null;
53
+ executionPlanId: string | null;
54
+ kernelPathId: string | null;
55
+ runtimeProfileHash: string | null;
56
+ backendIdentityHash: string | null;
57
+ observationPolicyId: DopplerObservationPolicyId;
58
+ };
59
+ inspectionReceipt: DopplerModelInspectionReceipt | null;
60
+ evidence: DopplerGenerationEvidence;
61
+ }
62
+
63
+ export type DopplerGenerationEvent =
64
+ | {
65
+ schema: 'doppler.generation-event/v1';
66
+ type: 'text-delta';
67
+ text: string;
68
+ observationPolicyId: DopplerObservationPolicyId;
69
+ }
70
+ | {
71
+ schema: 'doppler.generation-event/v1';
72
+ type: 'complete';
73
+ outputText: string;
74
+ observationPolicyId: DopplerObservationPolicyId;
75
+ };
76
+
77
+ export interface DopplerScopedModelSession {
78
+ readonly schema: 'doppler.scoped-session/v1';
79
+ readonly capabilities: Readonly<Record<DopplerCapability, boolean>>;
80
+ readonly closed: boolean;
81
+ readonly loaded: boolean;
82
+ readonly modelId: string;
83
+ readonly manifestHash: string | null;
84
+ readonly persistentCache: DopplerPersistentCacheReceipt | null;
85
+ readonly manifest: unknown;
86
+ readonly activeLoRA: string | null;
87
+ readonly deviceInfo: Record<string, unknown> | null;
88
+ readonly advanced: DopplerModelHandle['advanced'];
89
+ supports(capability: DopplerCapability): boolean;
90
+ require(capability: DopplerCapability): true;
91
+ generate(input: DopplerPromptInput, options?: DopplerScopedGenerateOptions): Promise<DopplerGenerationResult>;
92
+ stream(input: DopplerPromptInput, options?: DopplerScopedGenerateOptions): AsyncGenerator<DopplerGenerationEvent, void, void>;
93
+ inspect(
94
+ input: string,
95
+ options?: DopplerScopedGenerateOptions & {
96
+ topKSize?: number;
97
+ onEvent?: (event: { type: 'inspection-complete'; receipt: DopplerModelInspectionReceipt }) => void;
98
+ }
99
+ ): Promise<DopplerModelInspectionReceipt>;
100
+ embed(input: string, options?: Record<string, unknown>): Promise<unknown>;
101
+ encodeSequence(sequence: string, options?: SequenceEncodeOptions): Promise<SequenceEncodeResult>;
102
+ loadLoRA(adapter: unknown, options?: Record<string, unknown>): Promise<void>;
103
+ unloadLoRA(): Promise<void>;
104
+ resetGenerationState(): void;
105
+ close(): Promise<void>;
106
+ }
107
+
108
+ export declare const OBSERVATION_POLICIES: Readonly<Record<
109
+ DopplerObservationTier,
110
+ {
111
+ id: DopplerObservationPolicyId;
112
+ tier: DopplerObservationTier;
113
+ executionClassification: 'representative' | 'observed' | 'deep-diagnostic';
114
+ }
115
+ >>;
116
+
117
+ export declare function createScopedModelSession(handle: DopplerModelHandle): DopplerScopedModelSession;