doppler-gpu 0.4.15 → 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 (221) hide show
  1. package/README.md +9 -0
  2. package/package.json +25 -2
  3. package/src/cli/doppler-cli.js +253 -94
  4. package/src/cli/runtime-profiles.js +3 -7
  5. package/src/client/doppler-api.d.ts +28 -0
  6. package/src/client/doppler-api.js +2 -0
  7. package/src/client/inspection.d.ts +122 -0
  8. package/src/client/inspection.js +343 -0
  9. package/src/client/runtime/index.d.ts +54 -0
  10. package/src/client/runtime/index.js +190 -18
  11. package/src/client/runtime/model-manager.d.ts +0 -4
  12. package/src/client/runtime/model-manager.js +0 -28
  13. package/src/client/runtime/model-session.d.ts +48 -1
  14. package/src/client/runtime/model-session.js +149 -30
  15. package/src/client/runtime/model-source.d.ts +10 -1
  16. package/src/client/runtime/scoped-session.d.ts +117 -0
  17. package/src/client/runtime/scoped-session.js +257 -0
  18. package/src/client/runtime/types.d.ts +0 -1
  19. package/src/client/runtime/types.js +0 -1
  20. package/src/config/evidence/boundary-evidence-policy.json +54 -0
  21. package/src/config/evidence/source-intake-policy.json +122 -0
  22. package/src/config/inspection/observation-policies.json +80 -0
  23. package/src/config/param-validator.js +21 -36
  24. package/src/config/runtime/compute/f16-activations.json +1 -0
  25. package/src/config/runtime/compute/f16-batched.json +1 -0
  26. package/src/config/runtime/default.json +1 -0
  27. package/src/config/runtime/diagnostics/debug-logits.json +1 -0
  28. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-alt.json +1 -0
  29. package/src/config/runtime/experiments/bench/gemma3-bench-q4k-batched.json +1 -0
  30. package/src/config/runtime/experiments/bench/gemma3-bench-q4k.json +1 -0
  31. package/src/config/runtime/experiments/bench/gemma4-bench-q4k.json +1 -0
  32. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-alt.json +1 -0
  33. package/src/config/runtime/experiments/bench/qwen3-bench-q4k-batched.json +1 -0
  34. package/src/config/runtime/experiments/debug/gemma3-browser-diagnose-q4k.json +1 -1
  35. package/src/config/runtime/experiments/debug/gemma3-debug-q4k.json +1 -3
  36. package/src/config/runtime/experiments/debug/gemma4-e2b-browser-diagnose-q4k.json +1 -1
  37. package/src/config/runtime/experiments/debug/qwen35-browser-diagnose-q4k.json +1 -1
  38. package/src/config/runtime/experiments/verify/gemma3-verify.json +1 -3
  39. package/src/config/runtime/experiments/verify/gemma4-e2b-verify.json +1 -3
  40. package/src/config/runtime/experiments/verify/lfm2-verify.json +1 -3
  41. package/src/config/runtime/experiments/verify/translategemma-verify.json +1 -3
  42. package/src/config/runtime/model/gemma2-debug.json +1 -0
  43. package/src/config/runtime/model/gemma2-pipeline-debug.json +1 -0
  44. package/src/config/runtime/model/gemma2-pipeline.json +1 -0
  45. package/src/config/runtime/model/gemma3-layer-probe.json +1 -0
  46. package/src/config/runtime/model/qwen3-5-layer-probe.json +1 -0
  47. package/src/config/runtime/model/qwen3-5-layer3-boundary-probe.json +1 -0
  48. package/src/config/runtime/model/qwen3-5-linear-attn-debug.json +1 -0
  49. package/src/config/runtime/optimization-candidates/registry.json +5 -0
  50. package/src/config/runtime/platform/metal-apple-q4k.json +1 -0
  51. package/src/config/runtime/profiles/default.json +1 -0
  52. package/src/config/runtime/profiles/diffusiongemma-26b-a4b-throughput.json +1 -0
  53. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-overlapped-probe.json +1 -0
  54. package/src/config/runtime/profiles/gemma3-270m-q4k-throughput-probe.json +1 -0
  55. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-b4.json +1 -3
  56. package/src/config/runtime/profiles/gemma4-12b-rdrr-safe-single.json +1 -3
  57. package/src/config/runtime/profiles/gemma4-31b-f16-activations-probe.json +1 -5
  58. package/src/config/runtime/profiles/gemma4-e2b-baseline-probe.json +1 -3
  59. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-probe.json +1 -3
  60. package/src/config/runtime/profiles/gemma4-e2b-fused-rmsnorm-test.json +1 -0
  61. package/src/config/runtime/profiles/gemma4-e2b-int4ple-baseline-probe.json +1 -5
  62. package/src/config/runtime/profiles/gemma4-e2b-int4ple-f16a-probe.json +1 -5
  63. package/src/config/runtime/profiles/gemma4-e2b-int4ple-reference-export.json +1 -3
  64. package/src/config/runtime/profiles/gemma4-e2b-int4ple-retain-q4k-probe.json +1 -5
  65. package/src/config/runtime/profiles/gemma4-e2b-low-memory.json +1 -0
  66. package/src/config/runtime/profiles/gemma4-e2b-prefill-profile.json +1 -3
  67. package/src/config/runtime/profiles/gemma4-e2b-throughput-probe.json +1 -0
  68. package/src/config/runtime/profiles/low-memory.json +1 -0
  69. package/src/config/runtime/profiles/production.json +1 -3
  70. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-attn128-candidate.json +1 -0
  71. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-maxbatch64-candidate.json +1 -0
  72. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-normed-ffn-candidate.json +1 -0
  73. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-overlap-ringtokens1-candidate.json +1 -0
  74. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-parity.json +1 -0
  75. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-sequential-candidate.json +1 -0
  76. package/src/config/runtime/profiles/qwen-3-5-0-8b-metal-throughput.json +1 -0
  77. package/src/config/runtime/profiles/qwen-3-5-0-8b-prefill-profile.json +1 -3
  78. package/src/config/runtime/profiles/qwen-3-5-0-8b-throughput-probe.json +1 -0
  79. package/src/config/runtime/profiles/qwen-3-5-2b-f16-primary-throughput.json +1 -5
  80. package/src/config/runtime/profiles/qwen-3-5-2b-metal-parity.json +1 -0
  81. package/src/config/runtime/profiles/qwen-3-5-2b-metal-throughput.json +1 -0
  82. package/src/config/runtime/profiles/qwen-3-5-9b-metal-correctness.json +1 -0
  83. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-stability.json +1 -3
  84. package/src/config/runtime/profiles/qwen-3-embedding-0-6b-metal-throughput.json +1 -0
  85. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-stability.json +1 -0
  86. package/src/config/runtime/profiles/qwen-3-reranker-0-6b-metal-throughput.json +1 -0
  87. package/src/config/runtime/profiles/qwen3-6-27b-f16-activations-probe.json +1 -5
  88. package/src/config/runtime/profiles/rerank-stability.json +1 -3
  89. package/src/config/runtime/profiles/rerank-throughput.json +1 -3
  90. package/src/config/runtime/profiles/simulation.json +1 -3
  91. package/src/config/runtime/profiles/throughput.json +1 -3
  92. package/src/config/runtime/profiles/trace-layers.json +1 -3
  93. package/src/config/runtime/profiles/translategemma-1b-nativekd2-q4k-rdna3-throughput-probe.json +1 -0
  94. package/src/config/runtime/profiles/turboquant-contiguous-prod.json +1 -0
  95. package/src/config/runtime/profiles/turboquant-contiguous.json +1 -0
  96. package/src/config/runtime/profiles/turboquant.json +1 -0
  97. package/src/config/runtime/profiles/vector-stability.json +1 -3
  98. package/src/config/runtime/profiles/vector-throughput.json +1 -0
  99. package/src/config/runtime/profiles/verbose-trace.json +1 -3
  100. package/src/config/runtime/tiers/gemma4-128gb.json +1 -0
  101. package/src/config/runtime/tiers/gemma4-16gb.json +1 -0
  102. package/src/config/runtime/tiers/gemma4-24gb.json +1 -0
  103. package/src/config/runtime/tiers/gemma4-32gb.json +1 -0
  104. package/src/config/schema/benchmark.schema.d.ts +7 -0
  105. package/src/config/schema/benchmark.schema.js +5 -0
  106. package/src/config/schema/index.d.ts +8 -16
  107. package/src/config/schema/index.js +5 -8
  108. package/src/config/schema/kernel-thresholds.schema.d.ts +0 -12
  109. package/src/config/schema/kernel-thresholds.schema.js +0 -12
  110. package/src/config/schema/kernel-warmup.schema.d.ts +1 -3
  111. package/src/config/schema/kernel-warmup.schema.js +0 -1
  112. package/src/config/schema/runtime-profile.schema.d.ts +24 -0
  113. package/src/config/schema/runtime-profile.schema.js +92 -0
  114. package/src/config/schema/shared-runtime.schema.d.ts +1 -4
  115. package/src/config/schema/shared-runtime.schema.js +0 -2
  116. package/src/config/schema/tooling.schema.d.ts +8 -5
  117. package/src/config/schema/tooling.schema.js +3 -2
  118. package/src/debug/tensor.d.ts +2 -0
  119. package/src/debug/tensor.js +21 -2
  120. package/src/gpu/command-recorder.d.ts +5 -0
  121. package/src/gpu/command-recorder.js +17 -0
  122. package/src/gpu/kernel-runtime.js +2 -10
  123. package/src/gpu/kernels/index.d.ts +0 -2
  124. package/src/gpu/kernels/index.js +0 -2
  125. package/src/gpu/kernels/kernel-prewarm.d.ts +3 -0
  126. package/src/gpu/kernels/kernel-prewarm.js +60 -0
  127. package/src/gpu/kernels/utils.d.ts +2 -4
  128. package/src/gpu/kernels/utils.js +2 -4
  129. package/src/index.d.ts +13 -1
  130. package/src/index.js +7 -1
  131. package/src/inference/browser-harness-model-helpers.js +4 -0
  132. package/src/inference/browser-harness-runtime-helpers.js +25 -10
  133. package/src/inference/browser-harness-text-helpers.js +4 -1
  134. package/src/inference/browser-harness.d.ts +4 -0
  135. package/src/inference/browser-harness.js +91 -4
  136. package/src/inference/observation-context.d.ts +22 -0
  137. package/src/inference/observation-context.js +41 -0
  138. package/src/inference/pipelines/text/attention/attn-config.js +1 -1
  139. package/src/inference/pipelines/text/attention/executor-immediate.js +42 -0
  140. package/src/inference/pipelines/text/attention/executor-recorded.js +29 -0
  141. package/src/inference/pipelines/text/attention/index.js +7 -0
  142. package/src/inference/pipelines/text/attention/interpreter.js +1334 -0
  143. package/src/inference/pipelines/text/attention/plan.d.ts +36 -0
  144. package/src/inference/pipelines/text/attention/plan.js +328 -0
  145. package/src/inference/pipelines/text/attention/receipt.js +60 -0
  146. package/src/inference/pipelines/text/attention/record.js +8 -1278
  147. package/src/inference/pipelines/text/attention/run.js +8 -1386
  148. package/src/inference/pipelines/text/generator-decode-policy.js +4 -1
  149. package/src/inference/pipelines/text/generator-helpers.js +2 -0
  150. package/src/inference/pipelines/text/generator-steps.js +32 -15
  151. package/src/inference/pipelines/text/generator.js +10 -5
  152. package/src/inference/pipelines/text/init.d.ts +3 -0
  153. package/src/inference/pipelines/text/layer-plan-gpu.js +2 -0
  154. package/src/inference/pipelines/text/layer.js +2 -0
  155. package/src/inference/pipelines/text/model-load.d.ts +0 -1
  156. package/src/inference/pipelines/text/model-load.js +2 -11
  157. package/src/inference/pipelines/text/probes.js +10 -0
  158. package/src/inference/pipelines/text/resolved-runtime-session.d.ts +56 -0
  159. package/src/inference/pipelines/text/resolved-runtime-session.js +175 -0
  160. package/src/inference/pipelines/text/state.d.ts +6 -0
  161. package/src/inference/pipelines/text/state.js +3 -0
  162. package/src/inference/pipelines/text/types.d.ts +6 -0
  163. package/src/inference/pipelines/text.js +16 -1
  164. package/src/inference/refactor-receipt.d.ts +49 -0
  165. package/src/inference/refactor-receipt.js +188 -0
  166. package/src/inference/resource-scope.d.ts +33 -0
  167. package/src/inference/resource-scope.js +168 -0
  168. package/src/inference/test-harness.d.ts +3 -0
  169. package/src/inference/test-harness.js +1 -0
  170. package/src/storage/model-cache.d.ts +53 -0
  171. package/src/storage/model-cache.js +550 -0
  172. package/src/tooling/boundary-evidence.d.ts +51 -0
  173. package/src/tooling/boundary-evidence.js +408 -0
  174. package/src/tooling/browser-command-runner.js +4 -4
  175. package/src/tooling/command-context.d.ts +25 -0
  176. package/src/tooling/command-context.js +53 -0
  177. package/src/tooling/command-runner-shared.js +22 -5
  178. package/src/tooling/demo-receipts.d.ts +56 -0
  179. package/src/tooling/demo-receipts.js +113 -0
  180. package/src/tooling/diagnose-runner.js +2 -2
  181. package/src/tooling/execution-cost-ledger.d.ts +21 -0
  182. package/src/tooling/execution-cost-ledger.js +199 -0
  183. package/src/tooling/node-command-runner.js +2 -2
  184. package/src/tooling/opfs-cache.d.ts +11 -49
  185. package/src/tooling/opfs-cache.js +4 -510
  186. package/src/tooling/precision-replay-math.d.ts +42 -0
  187. package/src/tooling/precision-replay-math.js +174 -0
  188. package/src/tooling/program-bundle-parity.d.ts +3 -0
  189. package/src/tooling/program-bundle-parity.js +8 -0
  190. package/src/tooling/program-bundle.d.ts +1 -52
  191. package/src/tooling/program-bundle.js +0 -139
  192. package/src/tooling/registered-variant-calibration.d.ts +24 -0
  193. package/src/tooling/registered-variant-calibration.js +286 -0
  194. package/src/tooling/runtime-input-composition.js +105 -53
  195. package/src/tooling/runtime-intent.js +41 -0
  196. package/src/tooling/runtime-optimization-index.d.ts +6 -0
  197. package/src/tooling/runtime-optimization-index.js +72 -0
  198. package/src/tooling/runtime-optimization.d.ts +47 -6
  199. package/src/tooling/runtime-optimization.js +559 -40
  200. package/src/tooling/source-intake.d.ts +49 -0
  201. package/src/tooling/source-intake.js +414 -0
  202. package/src/tooling-exports/evidence.d.ts +34 -0
  203. package/src/tooling-exports/evidence.js +34 -0
  204. package/src/tooling-exports/runtime.d.ts +7 -0
  205. package/src/tooling-exports/runtime.js +7 -0
  206. package/src/tooling-exports.d.ts +11 -0
  207. package/src/tooling-exports.js +6 -3
  208. package/src/tooling-exports.shared.d.ts +32 -0
  209. package/src/tooling-exports.shared.js +31 -0
  210. package/src/version.js +1 -1
  211. package/src/config/schema/tuner.schema.d.ts +0 -39
  212. package/src/config/schema/tuner.schema.js +0 -13
  213. package/src/gpu/kernel-tuner/benchmarks.js +0 -902
  214. package/src/gpu/kernel-tuner/cache.js +0 -145
  215. package/src/gpu/kernel-tuner/index.js +0 -38
  216. package/src/gpu/kernel-tuner/tuner.js +0 -247
  217. package/src/gpu/kernel-tuner.js +0 -12
  218. package/src/gpu/kernels/kernel-tuning.d.ts +0 -42
  219. package/src/gpu/kernels/kernel-tuning.js +0 -158
  220. package/src/gpu/profiler.js +0 -382
  221. package/src/inference/pipelines/text/attention/output-gate-fusion.js +0 -37
@@ -0,0 +1,122 @@
1
+ export type DopplerClaimType =
2
+ | 'execution-identity'
3
+ | 'coarse-performance'
4
+ | 'quality-inspection'
5
+ | 'diagnostic';
6
+
7
+ export interface DopplerObservationPolicy {
8
+ id: string;
9
+ label: string;
10
+ modifiesExecution: boolean;
11
+ performanceRepresentative: boolean;
12
+ requiredCaptures: string[];
13
+ allowedClaimTypes: DopplerClaimType[];
14
+ gpuTimestampQueries: boolean;
15
+ perplexity: null | {
16
+ wordSegmentation: 'doppler.word-segmentation/unicode-whitespace-v1';
17
+ aggregation: 'doppler.perplexity/summed-word-surprisal-v1';
18
+ rollingWindow: {
19
+ unit: 'words' | 'tokens';
20
+ size: number;
21
+ };
22
+ };
23
+ }
24
+
25
+ export interface DopplerComparisonFingerprint {
26
+ schema: 'doppler.comparison-fingerprint/v1';
27
+ identity: {
28
+ artifact: {
29
+ modelId: string;
30
+ manifestHash: string;
31
+ };
32
+ tokenizer: {
33
+ contract: unknown;
34
+ digest: string;
35
+ };
36
+ promptTokenIds: number[];
37
+ sampling: Record<string, unknown>;
38
+ observationPolicy: {
39
+ id: string;
40
+ modifiesExecution: boolean;
41
+ performanceRepresentative: boolean;
42
+ requiredCaptures: string[];
43
+ allowedClaimTypes: DopplerClaimType[];
44
+ };
45
+ perplexity: DopplerObservationPolicy['perplexity'];
46
+ execution: Record<string, unknown>;
47
+ browser: Record<string, string>;
48
+ adapter: Record<string, string | null>;
49
+ };
50
+ fullDigest: string;
51
+ qualityDigest: string;
52
+ performanceDigest: string;
53
+ }
54
+
55
+ export interface DopplerInspectionTokenRecord {
56
+ index: number;
57
+ tokenId: number;
58
+ text: string;
59
+ probability: number | null;
60
+ surprisal: number | null;
61
+ topCandidates: Array<{
62
+ tokenId: number;
63
+ logit: number;
64
+ text: string;
65
+ probability: number | null;
66
+ }>;
67
+ }
68
+
69
+ export interface DopplerWordQualityRecord {
70
+ wordIndex: number;
71
+ text: string;
72
+ tokenIndexes: number[];
73
+ tokenCount: number;
74
+ summedSurprisal: number;
75
+ probabilityAvailable: boolean;
76
+ rollingPerplexity: number | null;
77
+ cumulativePerplexity: number | null;
78
+ rollingWindow: {
79
+ unit: 'words' | 'tokens';
80
+ size: number;
81
+ tokenCount: number;
82
+ };
83
+ }
84
+
85
+ export declare const OBSERVATION_POLICY_REGISTRY_SCHEMA: 'doppler.observation-policy-registry/v1';
86
+ export declare const COMPARISON_FINGERPRINT_SCHEMA: 'doppler.comparison-fingerprint/v1';
87
+ export declare const MODEL_INSPECTION_RECEIPT_SCHEMA: 'doppler.model-inspection-receipt/v1';
88
+ export declare const WORD_SEGMENTATION_SCHEMA: 'doppler.word-segmentation/unicode-whitespace-v1';
89
+ export declare const PERPLEXITY_AGGREGATION_SCHEMA: 'doppler.perplexity/summed-word-surprisal-v1';
90
+
91
+ export declare function listObservationPolicies(): DopplerObservationPolicy[];
92
+ export declare function resolveObservationPolicy(policyId?: string): DopplerObservationPolicy;
93
+ export declare function buildComparisonFingerprint(input: {
94
+ artifact: { modelId: string; manifestHash: string };
95
+ tokenizer: unknown;
96
+ promptTokenIds: readonly number[];
97
+ sampling?: Record<string, unknown>;
98
+ observationPolicyId: string;
99
+ execution?: Record<string, unknown>;
100
+ browser?: Record<string, unknown>;
101
+ adapter?: Record<string, unknown>;
102
+ }): DopplerComparisonFingerprint;
103
+ export declare function assertComparableFingerprints(
104
+ kind: 'quality' | 'performance',
105
+ left: DopplerComparisonFingerprint,
106
+ right: DopplerComparisonFingerprint
107
+ ): true;
108
+ export declare function buildInspectionTokenRecords(
109
+ tokenIds: readonly number[],
110
+ logitsByStep: ArrayLike<number>[],
111
+ tokenizer: { decode(ids: readonly number[], skipSpecialTokens?: boolean, cleanUp?: boolean): string },
112
+ topKSize?: number
113
+ ): DopplerInspectionTokenRecord[];
114
+ export declare function aggregateWordPerplexity(
115
+ tokenRecords: DopplerInspectionTokenRecord[],
116
+ options?: { windowUnit?: 'words' | 'tokens'; windowSize?: number }
117
+ ): {
118
+ wordSegmentation: 'doppler.word-segmentation/unicode-whitespace-v1';
119
+ aggregation: 'doppler.perplexity/summed-word-surprisal-v1';
120
+ rollingWindow: { unit: 'words' | 'tokens'; size: number };
121
+ words: DopplerWordQualityRecord[];
122
+ };
@@ -0,0 +1,343 @@
1
+ import observationPolicyRegistry from '../config/inspection/observation-policies.json' with { type: 'json' };
2
+ import { computeCanonicalSha256 } from '../utils/canonical-hash.js';
3
+
4
+ export const OBSERVATION_POLICY_REGISTRY_SCHEMA = 'doppler.observation-policy-registry/v1';
5
+ export const COMPARISON_FINGERPRINT_SCHEMA = 'doppler.comparison-fingerprint/v1';
6
+ export const MODEL_INSPECTION_RECEIPT_SCHEMA = 'doppler.model-inspection-receipt/v1';
7
+ export const WORD_SEGMENTATION_SCHEMA = 'doppler.word-segmentation/unicode-whitespace-v1';
8
+ export const PERPLEXITY_AGGREGATION_SCHEMA = 'doppler.perplexity/summed-word-surprisal-v1';
9
+
10
+ const COMPARISON_KINDS = new Set(['quality', 'performance']);
11
+ const policyById = new Map(
12
+ observationPolicyRegistry.policies.map((policy) => [policy.id, Object.freeze(policy)])
13
+ );
14
+
15
+ function assertPlainObject(value, label) {
16
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
17
+ throw new Error(`${label} must be an object.`);
18
+ }
19
+ }
20
+
21
+ function assertString(value, label) {
22
+ const normalized = String(value ?? '').trim();
23
+ if (!normalized) {
24
+ throw new Error(`${label} must be a non-empty string.`);
25
+ }
26
+ return normalized;
27
+ }
28
+
29
+ function normalizeSha256(value, label) {
30
+ const normalized = assertString(value, label).toLowerCase();
31
+ const digest = normalized.startsWith('sha256:') ? normalized : `sha256:${normalized}`;
32
+ if (!/^sha256:[0-9a-f]{64}$/.test(digest)) {
33
+ throw new Error(`${label} must be a SHA-256 digest.`);
34
+ }
35
+ return digest;
36
+ }
37
+
38
+ function normalizeIntegerIds(values, label) {
39
+ if (!Array.isArray(values) && !ArrayBuffer.isView(values)) {
40
+ throw new Error(`${label} must be an array of token IDs.`);
41
+ }
42
+ const ids = Array.from(values, Number);
43
+ if (ids.some((value) => !Number.isInteger(value) || value < 0)) {
44
+ throw new Error(`${label} must contain non-negative integers.`);
45
+ }
46
+ return ids;
47
+ }
48
+
49
+ function cloneJson(value) {
50
+ return value == null ? value : JSON.parse(JSON.stringify(value));
51
+ }
52
+
53
+ function normalizeBrowserIdentity(value = {}) {
54
+ return {
55
+ userAgent: String(value.userAgent ?? ''),
56
+ platform: String(value.platform ?? ''),
57
+ language: String(value.language ?? ''),
58
+ };
59
+ }
60
+
61
+ function normalizeAdapterIdentity(value = {}) {
62
+ return {
63
+ vendor: value.vendor == null ? null : String(value.vendor),
64
+ architecture: value.architecture == null ? null : String(value.architecture),
65
+ device: value.device == null ? null : String(value.device),
66
+ description: value.description == null ? null : String(value.description),
67
+ };
68
+ }
69
+
70
+ function normalizeExecutionIdentity(value = {}) {
71
+ return {
72
+ backend: value.backend == null ? null : String(value.backend),
73
+ executionPlanId: value.executionPlanId == null ? null : String(value.executionPlanId),
74
+ kernelPathId: value.kernelPathId == null ? null : String(value.kernelPathId),
75
+ kernelPathSource: value.kernelPathSource == null ? null : String(value.kernelPathSource),
76
+ activationDtype: value.activationDtype == null ? null : String(value.activationDtype),
77
+ hasF16: value.hasF16 === true,
78
+ hasSubgroups: value.hasSubgroups === true,
79
+ };
80
+ }
81
+
82
+ function buildQualityIdentity(identity) {
83
+ return {
84
+ artifact: identity.artifact,
85
+ tokenizer: identity.tokenizer,
86
+ promptTokenIds: identity.promptTokenIds,
87
+ sampling: identity.sampling,
88
+ observationPolicy: identity.observationPolicy,
89
+ perplexity: identity.perplexity,
90
+ };
91
+ }
92
+
93
+ function buildPerformanceIdentity(identity) {
94
+ return {
95
+ artifact: identity.artifact,
96
+ tokenizer: identity.tokenizer,
97
+ promptTokenIds: identity.promptTokenIds,
98
+ sampling: identity.sampling,
99
+ observationPolicy: identity.observationPolicy,
100
+ execution: identity.execution,
101
+ browser: identity.browser,
102
+ adapter: identity.adapter,
103
+ };
104
+ }
105
+
106
+ export function listObservationPolicies() {
107
+ return observationPolicyRegistry.policies.map((policy) => cloneJson(policy));
108
+ }
109
+
110
+ export function resolveObservationPolicy(policyId = observationPolicyRegistry.defaultPolicyId) {
111
+ const normalized = assertString(policyId, 'observation policy id');
112
+ const policy = policyById.get(normalized);
113
+ if (!policy) {
114
+ throw new Error(`Unknown observation policy "${normalized}".`);
115
+ }
116
+ if (policy.performanceRepresentative && policy.modifiesExecution) {
117
+ throw new Error(`${normalized}: a policy that modifies execution cannot represent performance.`);
118
+ }
119
+ if (policy.performanceRepresentative && policy.gpuTimestampQueries) {
120
+ throw new Error(`${normalized}: representative coarse timing cannot enable GPU timestamp queries.`);
121
+ }
122
+ return cloneJson(policy);
123
+ }
124
+
125
+ export function buildComparisonFingerprint(input) {
126
+ assertPlainObject(input, 'comparison fingerprint input');
127
+ const policy = resolveObservationPolicy(input.observationPolicyId);
128
+ const promptTokenIds = normalizeIntegerIds(input.promptTokenIds, 'promptTokenIds');
129
+ const artifact = {
130
+ modelId: assertString(input.artifact?.modelId, 'artifact.modelId'),
131
+ manifestHash: normalizeSha256(input.artifact?.manifestHash, 'artifact.manifestHash'),
132
+ };
133
+ const tokenizerContract = cloneJson(input.tokenizer ?? null);
134
+ if (!tokenizerContract) {
135
+ throw new Error('comparison fingerprint requires tokenizer identity.');
136
+ }
137
+ const tokenizer = {
138
+ contract: tokenizerContract,
139
+ digest: computeCanonicalSha256(tokenizerContract),
140
+ };
141
+ const identity = {
142
+ artifact,
143
+ tokenizer,
144
+ promptTokenIds,
145
+ sampling: cloneJson(input.sampling ?? {}),
146
+ observationPolicy: {
147
+ id: policy.id,
148
+ modifiesExecution: policy.modifiesExecution,
149
+ performanceRepresentative: policy.performanceRepresentative,
150
+ requiredCaptures: [...policy.requiredCaptures],
151
+ allowedClaimTypes: [...policy.allowedClaimTypes],
152
+ },
153
+ perplexity: cloneJson(policy.perplexity),
154
+ execution: normalizeExecutionIdentity(input.execution),
155
+ browser: normalizeBrowserIdentity(input.browser),
156
+ adapter: normalizeAdapterIdentity(input.adapter),
157
+ };
158
+ return {
159
+ schema: COMPARISON_FINGERPRINT_SCHEMA,
160
+ identity,
161
+ fullDigest: computeCanonicalSha256(identity),
162
+ qualityDigest: computeCanonicalSha256(buildQualityIdentity(identity)),
163
+ performanceDigest: computeCanonicalSha256(buildPerformanceIdentity(identity)),
164
+ };
165
+ }
166
+
167
+ export function assertComparableFingerprints(kind, left, right) {
168
+ if (!COMPARISON_KINDS.has(kind)) {
169
+ throw new Error(`Comparison kind must be "quality" or "performance"; received "${kind}".`);
170
+ }
171
+ if (left?.schema !== COMPARISON_FINGERPRINT_SCHEMA || right?.schema !== COMPARISON_FINGERPRINT_SCHEMA) {
172
+ throw new Error('Both values must be Doppler comparison fingerprints.');
173
+ }
174
+ if (kind === 'quality') {
175
+ if (left.identity?.tokenizer?.digest !== right.identity?.tokenizer?.digest) {
176
+ throw new Error('Quality comparison rejected: tokenizer identities differ.');
177
+ }
178
+ if (left.qualityDigest !== right.qualityDigest) {
179
+ throw new Error('Quality comparison rejected: canonical quality fingerprints differ.');
180
+ }
181
+ } else {
182
+ if (left.performanceDigest !== right.performanceDigest) {
183
+ throw new Error('Performance comparison rejected: canonical performance fingerprints differ.');
184
+ }
185
+ if (left.identity?.observationPolicy?.performanceRepresentative !== true) {
186
+ throw new Error('Performance comparison rejected: observation policy is not representative.');
187
+ }
188
+ if (right.identity?.observationPolicy?.performanceRepresentative !== true) {
189
+ throw new Error('Performance comparison rejected: observation policy is not representative.');
190
+ }
191
+ }
192
+ return true;
193
+ }
194
+
195
+ function selectedProbability(logits, tokenId) {
196
+ if (!logits || !Number.isInteger(tokenId) || tokenId < 0 || tokenId >= logits.length) {
197
+ return null;
198
+ }
199
+ let maximum = -Infinity;
200
+ for (let index = 0; index < logits.length; index += 1) {
201
+ const value = Number(logits[index]);
202
+ if (Number.isFinite(value) && value > maximum) maximum = value;
203
+ }
204
+ if (!Number.isFinite(maximum)) return null;
205
+ let denominator = 0;
206
+ for (let index = 0; index < logits.length; index += 1) {
207
+ denominator += Math.exp(Number(logits[index]) - maximum);
208
+ }
209
+ if (!Number.isFinite(denominator) || denominator <= 0) return null;
210
+ return Math.exp(Number(logits[tokenId]) - maximum) / denominator;
211
+ }
212
+
213
+ function topCandidates(logits, tokenizer, count) {
214
+ if (!logits || !Number.isInteger(count) || count <= 0) return [];
215
+ const candidates = [];
216
+ for (let tokenId = 0; tokenId < logits.length; tokenId += 1) {
217
+ const logit = Number(logits[tokenId]);
218
+ if (!Number.isFinite(logit)) continue;
219
+ if (candidates.length < count) {
220
+ candidates.push({ tokenId, logit });
221
+ candidates.sort((left, right) => right.logit - left.logit);
222
+ continue;
223
+ }
224
+ if (logit > candidates[candidates.length - 1].logit) {
225
+ candidates[candidates.length - 1] = { tokenId, logit };
226
+ candidates.sort((left, right) => right.logit - left.logit);
227
+ }
228
+ }
229
+ const maximum = candidates[0]?.logit ?? -Infinity;
230
+ let denominator = 0;
231
+ for (let index = 0; index < logits.length; index += 1) {
232
+ denominator += Math.exp(Number(logits[index]) - maximum);
233
+ }
234
+ return candidates.map((candidate) => ({
235
+ ...candidate,
236
+ text: String(tokenizer.decode([candidate.tokenId], true, false)),
237
+ probability: denominator > 0 ? Math.exp(candidate.logit - maximum) / denominator : null,
238
+ }));
239
+ }
240
+
241
+ function segmentTokenRecords(tokenRecords) {
242
+ const words = [];
243
+ let current = null;
244
+ const flush = () => {
245
+ if (!current) return;
246
+ current.wordIndex = words.length;
247
+ words.push(current);
248
+ current = null;
249
+ };
250
+ for (const token of tokenRecords) {
251
+ const pieces = String(token.text ?? '').split(/(\s+)/u).filter(Boolean);
252
+ if (pieces.length === 0) {
253
+ pieces.push('');
254
+ }
255
+ for (const piece of pieces) {
256
+ if (/^\s+$/u.test(piece)) {
257
+ flush();
258
+ continue;
259
+ }
260
+ if (!current) {
261
+ current = {
262
+ text: '',
263
+ tokenIndexes: [],
264
+ tokenCount: 0,
265
+ summedSurprisal: 0,
266
+ probabilityAvailable: true,
267
+ };
268
+ }
269
+ current.text += piece;
270
+ if (!current.tokenIndexes.includes(token.index)) {
271
+ current.tokenIndexes.push(token.index);
272
+ current.tokenCount += 1;
273
+ if (Number.isFinite(token.surprisal)) {
274
+ current.summedSurprisal += token.surprisal;
275
+ } else {
276
+ current.probabilityAvailable = false;
277
+ }
278
+ }
279
+ }
280
+ }
281
+ flush();
282
+ return words;
283
+ }
284
+
285
+ export function aggregateWordPerplexity(tokenRecords, options = {}) {
286
+ const windowUnit = options.windowUnit ?? 'words';
287
+ const windowSize = Number(options.windowSize ?? 8);
288
+ if (windowUnit !== 'words' && windowUnit !== 'tokens') {
289
+ throw new Error('Perplexity rolling window unit must be "words" or "tokens".');
290
+ }
291
+ if (!Number.isInteger(windowSize) || windowSize <= 0) {
292
+ throw new Error('Perplexity rolling window size must be a positive integer.');
293
+ }
294
+ const words = segmentTokenRecords(tokenRecords);
295
+ let cumulativeSurprisal = 0;
296
+ let cumulativeTokens = 0;
297
+ for (let index = 0; index < words.length; index += 1) {
298
+ const word = words[index];
299
+ if (word.probabilityAvailable) {
300
+ cumulativeSurprisal += word.summedSurprisal;
301
+ cumulativeTokens += word.tokenCount;
302
+ }
303
+ let selected = [];
304
+ if (windowUnit === 'words') {
305
+ selected = words.slice(Math.max(0, index - windowSize + 1), index + 1);
306
+ } else {
307
+ let remaining = windowSize;
308
+ for (let cursor = index; cursor >= 0 && remaining > 0; cursor -= 1) {
309
+ selected.unshift(words[cursor]);
310
+ remaining -= words[cursor].tokenCount;
311
+ }
312
+ }
313
+ const available = selected.filter((entry) => entry.probabilityAvailable);
314
+ const rollingTokens = available.reduce((sum, entry) => sum + entry.tokenCount, 0);
315
+ const rollingSurprisal = available.reduce((sum, entry) => sum + entry.summedSurprisal, 0);
316
+ word.rollingPerplexity = rollingTokens > 0 ? Math.exp(rollingSurprisal / rollingTokens) : null;
317
+ word.cumulativePerplexity = cumulativeTokens > 0
318
+ ? Math.exp(cumulativeSurprisal / cumulativeTokens)
319
+ : null;
320
+ word.rollingWindow = { unit: windowUnit, size: windowSize, tokenCount: rollingTokens };
321
+ }
322
+ return {
323
+ wordSegmentation: WORD_SEGMENTATION_SCHEMA,
324
+ aggregation: PERPLEXITY_AGGREGATION_SCHEMA,
325
+ rollingWindow: { unit: windowUnit, size: windowSize },
326
+ words,
327
+ };
328
+ }
329
+
330
+ export function buildInspectionTokenRecords(tokenIds, logitsByStep, tokenizer, topKSize = 5) {
331
+ return tokenIds.map((tokenId, index) => {
332
+ const logits = logitsByStep[index] ?? null;
333
+ const probability = selectedProbability(logits, tokenId);
334
+ return {
335
+ index,
336
+ tokenId,
337
+ text: String(tokenizer.decode([tokenId], true, false)),
338
+ probability,
339
+ surprisal: probability && probability > 0 ? -Math.log(probability) : null,
340
+ topCandidates: topCandidates(logits, tokenizer, topKSize),
341
+ };
342
+ });
343
+ }
@@ -5,8 +5,16 @@ import type {
5
5
  DopplerLoadOptions,
6
6
  DopplerLoadProgress,
7
7
  DopplerModelSource,
8
+ DopplerModelSourceResolution,
9
+ DopplerPersistentCacheReceipt,
8
10
  } from './model-source.js';
9
11
  import type { DopplerModelHandle } from './model-session.js';
12
+ import type {
13
+ DopplerGenerationResult,
14
+ DopplerPromptInput,
15
+ DopplerScopedGenerateOptions,
16
+ DopplerScopedModelSession,
17
+ } from './scoped-session.js';
10
18
 
11
19
  export type DopplerGenerateOptions = Omit<GenerateOptions, 'stopTokens'>;
12
20
 
@@ -22,12 +30,21 @@ export interface DopplerChatResponse {
22
30
  export interface DopplerNamespace {
23
31
  (prompt: string, options: DopplerCallOptions): AsyncGenerator<string, void, void>;
24
32
  load(model: DopplerModelSource, options?: DopplerLoadOptions): Promise<DopplerModelHandle>;
33
+ open(model: DopplerModelSource, options?: DopplerLoadOptions): Promise<DopplerScopedModelSession>;
34
+ generate(
35
+ model: DopplerModelSource,
36
+ input: DopplerPromptInput,
37
+ options?: DopplerLoadOptions & DopplerScopedGenerateOptions
38
+ ): Promise<DopplerGenerationResult>;
25
39
  text(prompt: string, options: DopplerCallOptions): Promise<string>;
26
40
  chat(messages: ChatMessage[], options: DopplerCallOptions): AsyncGenerator<string, void, void>;
27
41
  chatText(messages: ChatMessage[], options: DopplerCallOptions): Promise<DopplerChatResponse>;
28
42
  evict(model: DopplerModelSource): Promise<boolean>;
29
43
  evictAll(): Promise<void>;
30
44
  listModels(): Promise<string[]>;
45
+ listModelDetails(): Promise<Array<Record<string, unknown> & { modelId: string }>>;
46
+ listPersistentModels(): Promise<Array<Record<string, unknown> & { modelId: string }>>;
47
+ removePersistentModel(model: DopplerModelSource): Promise<boolean>;
31
48
  }
32
49
 
33
50
  export interface DopplerCallOptions extends DopplerGenerateOptions {
@@ -38,6 +55,12 @@ export interface DopplerCallOptions extends DopplerGenerateOptions {
38
55
  export interface DopplerRuntimeService {
39
56
  doppler: DopplerNamespace;
40
57
  load(model: DopplerModelSource, options?: DopplerLoadOptions): Promise<DopplerModelHandle>;
58
+ open(model: DopplerModelSource, options?: DopplerLoadOptions): Promise<DopplerScopedModelSession>;
59
+ generate(
60
+ model: DopplerModelSource,
61
+ input: DopplerPromptInput,
62
+ options?: DopplerLoadOptions & DopplerScopedGenerateOptions
63
+ ): Promise<DopplerGenerationResult>;
41
64
  clearModelCache(): void;
42
65
  resolveLoadProgressHandlers(options?: DopplerLoadOptions): {
43
66
  userProgress: ((event: DopplerLoadProgress) => void) | null;
@@ -51,13 +74,44 @@ export declare function createDopplerRuntimeService(options: {
51
74
  defaultLoadProgressLogger?: ((event: DopplerLoadProgress) => void) | null;
52
75
  }): DopplerRuntimeService;
53
76
 
77
+ export declare function resolvePersistentBrowserLoadSource(
78
+ loadSource: DopplerModelSourceResolution,
79
+ cache: false | 'opfs' | undefined,
80
+ onProgress?: ((event: DopplerLoadProgress) => void) | null,
81
+ cacheSource?: (
82
+ modelId: string,
83
+ modelBaseUrl: string,
84
+ onProgress: ((event: Record<string, unknown>) => void) | null,
85
+ options: { expectedManifestHash: string }
86
+ ) => Promise<{
87
+ storageContext: Record<string, unknown>;
88
+ storageBackend: 'opfs';
89
+ cacheState: 'hit' | 'verified-hit' | 'manifest-refresh' | 'imported';
90
+ fromCache: boolean;
91
+ manifestHash: string;
92
+ totalBytes: number;
93
+ }>
94
+ ): Promise<DopplerModelSourceResolution & {
95
+ persistentCache?: DopplerPersistentCacheReceipt;
96
+ }>;
97
+
54
98
  export type {
55
99
  DopplerLoadOptions,
56
100
  DopplerLoadProgress,
101
+ DopplerPersistentCacheReceipt,
57
102
  DopplerModelSource,
58
103
  DopplerModelSourceResolution,
59
104
  } from './model-source.js';
60
105
 
61
106
  export type { DopplerModelHandle } from './model-session.js';
107
+ export type {
108
+ DopplerGenerationEvent,
109
+ DopplerGenerationResult,
110
+ DopplerObservationPolicyId,
111
+ DopplerObservationTier,
112
+ DopplerPromptInput,
113
+ DopplerScopedGenerateOptions,
114
+ DopplerScopedModelSession,
115
+ } from './scoped-session.js';
62
116
  export type { PrefillResult, LogitsStepResult } from '../../inference/pipelines/text/types.d.ts';
63
117
  export type { LoRAManifest, ExtensionBridgeClient } from './types.js';