@simulatte/doppler 0.1.0

package/src/formats/rdrr/validation.js

@@ -0,0 +1,200 @@
+import { validateTensorConfigConsistency } from './tensor-config-validator.js';
+
+export function validateManifest(manifest) {
+  const errors = [];
+  const warnings = [];
+
+  const isDiffusion = manifest.modelType === 'diffusion';
+  const isEnergy = manifest.modelType === 'energy';
+
+  // Version check
+  const version = typeof manifest.version === 'string'
+    ? parseFloat(manifest.version)
+    : manifest.version;
+  if (typeof version !== 'number' || isNaN(version) || version < 1) {
+    errors.push(`Invalid version: ${manifest.version}`);
+  }
+
+  // Required string fields
+  if (!manifest.modelId || typeof manifest.modelId !== 'string') {
+    errors.push('Missing or invalid modelId field');
+  }
+
+  if (!manifest.modelType || typeof manifest.modelType !== 'string') {
+    errors.push('Missing or invalid modelType field');
+  }
+
+  if (!manifest.quantization || typeof manifest.quantization !== 'string') {
+    errors.push('Missing or invalid quantization field');
+  }
+
+  // Inference config (manifest-first: required for all models)
+  if (!manifest.inference || typeof manifest.inference !== 'object') {
+    errors.push('Missing or invalid inference field');
+  }
+
+  // Hash algorithm (required)
+  if (!manifest.hashAlgorithm) {
+    errors.push('Missing or invalid hashAlgorithm');
+  } else if (manifest.hashAlgorithm !== 'sha256' && manifest.hashAlgorithm !== 'blake3') {
+    errors.push(`Invalid hashAlgorithm: ${manifest.hashAlgorithm}`);
+  }
+
+  // EOS token ID (required for text models)
+  const eosTokenId = manifest.eos_token_id;
+  if (!isDiffusion && !isEnergy) {
+    if (eosTokenId === undefined) {
+      errors.push('Missing eos_token_id');
+    } else if (Array.isArray(eosTokenId)) {
+      if (eosTokenId.length === 0 || eosTokenId.some((id) => typeof id !== 'number')) {
+        errors.push('Invalid eos_token_id array');
+      }
+    } else if (typeof eosTokenId !== 'number') {
+      errors.push('Invalid eos_token_id');
+    }
+  } else if (eosTokenId != null) {
+    if (Array.isArray(eosTokenId)) {
+      if (eosTokenId.length === 0 || eosTokenId.some((id) => typeof id !== 'number')) {
+        errors.push('Invalid eos_token_id array');
+      }
+    } else if (typeof eosTokenId !== 'number') {
+      errors.push('Invalid eos_token_id');
+    }
+  }
+
+  // Architecture validation (skip for LoRA adapters)
+  const isLoRAAdapter = manifest.adapterType === 'lora' || manifest.modelType === 'lora' || !!manifest.loraConfig;
+
+  if (!isLoRAAdapter && !isDiffusion && !isEnergy && manifest.architecture && typeof manifest.architecture === 'object') {
+    const arch = manifest.architecture;
+    const requiredFields = [
+      'numLayers',
+      'hiddenSize',
+      'intermediateSize',
+      'numAttentionHeads',
+      'numKeyValueHeads',
+      'headDim',
+      'vocabSize',
+      'maxSeqLen',
+    ];
+    for (const field of requiredFields) {
+      const value = arch[field];
+      if (typeof value !== 'number' || value <= 0) {
+        errors.push(`Invalid architecture.${field}`);
+      }
+    }
+  } else if (!isLoRAAdapter && !isDiffusion && !isEnergy && !manifest.architecture) {
+    errors.push('Missing architecture field');
+  }
+
+  // Groups validation
+  if (manifest.groups && typeof manifest.groups === 'object') {
+    const numShards = manifest.shards?.length ?? 0;
+    for (const [groupId, group] of Object.entries(manifest.groups)) {
+      if (!group.type) {
+        errors.push(`Group '${groupId}' missing type`);
+      }
+      if (!group.version || typeof group.version !== 'string') {
+        errors.push(`Group '${groupId}' missing or invalid version`);
+      }
+      if (!Array.isArray(group.shards)) {
+        errors.push(`Group '${groupId}' missing shards array`);
+      } else {
+        for (const shardIdx of group.shards) {
+          if (shardIdx < 0 || shardIdx >= numShards) {
+            errors.push(`Group '${groupId}' references invalid shard index ${shardIdx}`);
+          }
+        }
+      }
+      if (!Array.isArray(group.tensors)) {
+        errors.push(`Group '${groupId}' missing tensors array`);
+      }
+      if (!group.hash || typeof group.hash !== 'string') {
+        errors.push(`Group '${groupId}' missing or invalid hash`);
+      }
+    }
+  }
+
+  // Tensors requirement
+  const hasTensorsFile = manifest.tensorsFile && typeof manifest.tensorsFile === 'string';
+  const hasInlineTensors = manifest.tensors && typeof manifest.tensors === 'object';
+  if (!hasTensorsFile && !hasInlineTensors && !manifest.groups) {
+    errors.push('Missing tensorsFile and tensors - one is required');
+  }
+  if (hasInlineTensors) {
+    for (const [name, tensor] of Object.entries(manifest.tensors)) {
+      if (!tensor.role || typeof tensor.role !== 'string') {
+        errors.push(`Tensor "${name}" missing role`);
+      }
+    }
+  }
+
+  // MoE config validation
+  if (manifest.moeConfig !== null && manifest.moeConfig !== undefined) {
+    const moe = manifest.moeConfig;
+    if (typeof moe.numExperts !== 'number' || moe.numExperts <= 0) {
+      errors.push('Invalid moeConfig.numExperts');
+    }
+    if (typeof moe.numExpertsPerToken !== 'number' || moe.numExpertsPerToken <= 0) {
+      errors.push('Invalid moeConfig.numExpertsPerToken');
+    }
+    if (typeof moe.expertFormat !== 'string') {
+      errors.push('Invalid moeConfig.expertFormat');
+    } else if (moe.expertFormat !== 'mixtral' && moe.expertFormat !== 'gpt-oss') {
+      errors.push(`Invalid moeConfig.expertFormat: ${moe.expertFormat}`);
+    }
+    if (moe.numExpertsPerToken > moe.numExperts) {
+      errors.push('numExpertsPerToken cannot exceed numExperts');
+    }
+  }
+
+  // Shards validation
+  if (!Array.isArray(manifest.shards) || manifest.shards.length === 0) {
+    errors.push('Missing or empty shards array');
+  } else {
+    let expectedOffset = 0;
+    for (let i = 0; i < manifest.shards.length; i++) {
+      const shard = manifest.shards[i];
+
+      if (shard.index !== i) {
+        errors.push(`Shard ${i} has incorrect index: ${shard.index}`);
+      }
+
+      if (typeof shard.size !== 'number' || shard.size <= 0) {
+        errors.push(`Shard ${i} has invalid size`);
+      }
+
+      const hash = shard.hash;
+      if (!hash || typeof hash !== 'string' || hash.length !== 64) {
+        errors.push(`Shard ${i} has invalid hash`);
+      }
+
+      if (!shard.filename || typeof shard.filename !== 'string') {
+        errors.push(`Shard ${i} has invalid filename`);
+      }
+
+      if (shard.offset !== expectedOffset) {
+        errors.push(`Shard ${i} has incorrect offset: expected ${expectedOffset}, got ${shard.offset}`);
+      }
+      expectedOffset += shard.size;
+    }
+
+    if (manifest.totalSize !== expectedOffset) {
+      errors.push(`totalSize mismatch: declared ${manifest.totalSize}, calculated ${expectedOffset}`);
+    }
+  }
+
+  // Tensor-config consistency validation
+  // This catches bugs like postFeedforwardNorm=false when the weights exist
+  if (!isDiffusion && !isEnergy) {
+    const tensorConfigResult = validateTensorConfigConsistency(manifest);
+    for (const err of tensorConfigResult.errors) {
+      errors.push(`[${err.code}] ${err.message}${err.suggestion ? ` -> ${err.suggestion}` : ''}`);
+    }
+    for (const warn of tensorConfigResult.warnings) {
+      warnings.push(`[${warn.code}] ${warn.message}${warn.suggestion ? ` -> ${warn.suggestion}` : ''}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/formats/safetensors/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SafeTensors format module - types and parsing utilities.
+ *
+ * Browser code should import from './types.js' directly.
+ */
+
+// Re-export all types for browser-safe parsing
+export * from './types.js';

package/src/formats/safetensors/index.js

@@ -0,0 +1,4 @@
+
+
+// Re-export all types for browser-safe parsing
+export * from './types.js';

package/src/formats/safetensors/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared safetensors parsing utilities (browser + tools).
+ */
+
+export type SafetensorsDtype =
+  | 'F64'
+  | 'F32'
+  | 'F16'
+  | 'BF16'
+  | 'I64'
+  | 'I32'
+  | 'I16'
+  | 'I8'
+  | 'U8'
+  | 'BOOL';
+
+export type SafetensorsDType = SafetensorsDtype;
+
+export declare const DTYPE_SIZE: Record<SafetensorsDtype, number>;
+
+export declare const DTYPE_MAP: Record<string, string>;
+
+export interface SafetensorsTensor {
+  name: string;
+  shape: number[];
+  dtype: string;
+  dtypeOriginal?: string;
+  offset: number;
+  size: number;
+  elemSize?: number;
+  byteSize?: number;
+  shardFile?: string;
+  shardPath?: string;
+}
+
+export interface SafetensorsHeaderInfo {
+  dtype: string;
+  shape: number[];
+  data_offsets: [number, number];
+}
+
+export interface SafetensorsHeader {
+  __metadata__?: Record<string, string>;
+  [tensorName: string]: SafetensorsHeaderInfo | Record<string, string> | undefined;
+}
+
+export interface ParsedSafetensorsHeader {
+  headerSize: number;
+  dataOffset: number;
+  metadata: Record<string, string>;
+  tensors: SafetensorsTensor[];
+}
+
+export interface SafetensorsIndexJson {
+  weight_map: Record<string, string>;
+  metadata?: Record<string, unknown>;
+}
+
+export declare function parseSafetensorsIndexJsonText(text: string): SafetensorsIndexJson;
+
+export declare function parseSafetensorsHeader(buffer: ArrayBuffer): ParsedSafetensorsHeader;
+
+export declare function groupTensorsByLayer(
+  parsed: { tensors: SafetensorsTensor[] }
+): Map<number, SafetensorsTensor[]>;
+
+export declare function calculateTotalSize(parsed: { tensors: SafetensorsTensor[] }): number;

package/src/formats/safetensors/types.js

@@ -0,0 +1,102 @@
+
+
+import { MAX_HEADER_SIZE } from '../../config/schema/index.js';
+
+export const DTYPE_SIZE = {
+  F64: 8,
+  F32: 4,
+  F16: 2,
+  BF16: 2,
+  I64: 8,
+  I32: 4,
+  I16: 2,
+  I8: 1,
+  U8: 1,
+  BOOL: 1,
+};
+
+export const DTYPE_MAP = {
+  F64: 'F64',
+  F32: 'F32',
+  F16: 'F16',
+  BF16: 'BF16',
+  I64: 'I64',
+  I32: 'I32',
+  I16: 'I16',
+  I8: 'I8',
+  U8: 'U8',
+  BOOL: 'BOOL',
+};
+
+export function parseSafetensorsIndexJsonText(text) {
+  return JSON.parse(text);
+}
+
+export function parseSafetensorsHeader(buffer) {
+  const view = new DataView(buffer);
+
+  const headerSizeLow = view.getUint32(0, true);
+  const headerSizeHigh = view.getUint32(4, true);
+  const headerSize = headerSizeHigh * 0x100000000 + headerSizeLow;
+
+  if (headerSize > MAX_HEADER_SIZE) {
+    throw new Error(`Header too large: ${headerSize} bytes`);
+  }
+
+  if (buffer.byteLength < 8 + headerSize) {
+    throw new Error('Buffer does not contain full safetensors header');
+  }
+
+  const headerBytes = new Uint8Array(buffer, 8, headerSize);
+  const headerJson = new TextDecoder().decode(headerBytes);
+  const header = JSON.parse(headerJson);
+
+  const dataOffset = 8 + headerSize;
+  const metadata = (header.__metadata__ || {});
+  delete header.__metadata__;
+
+  const tensors = [];
+  for (const [name, info] of Object.entries(header)) {
+    if (!info || typeof info !== 'object' || !('dtype' in info)) continue;
+    const tensorInfo = info;
+    const { dtype, shape, data_offsets } = tensorInfo;
+    const [startOffset, endOffset] = data_offsets;
+    const elemSize = DTYPE_SIZE[dtype] || 1;
+
+    tensors.push({
+      name,
+      dtype: DTYPE_MAP[dtype] || dtype,
+      dtypeOriginal: dtype,
+      shape,
+      offset: dataOffset + startOffset,
+      size: endOffset - startOffset,
+      elemSize,
+      byteSize: elemSize,
+    });
+  }
+
+  tensors.sort((a, b) => a.offset - b.offset);
+
+  return { headerSize, dataOffset, metadata, tensors };
+}
+
+export function groupTensorsByLayer(parsed) {
+  const layers = new Map();
+
+  for (const tensor of parsed.tensors) {
+    const match = tensor.name.match(/layers?\.(\d+)\./);
+    if (match) {
+      const layerIdx = parseInt(match[1], 10);
+      if (!layers.has(layerIdx)) {
+        layers.set(layerIdx, []);
+      }
+      layers.get(layerIdx).push(tensor);
+    }
+  }
+
+  return layers;
+}
+
+export function calculateTotalSize(parsed) {
+  return parsed.tensors.reduce((sum, tensor) => sum + tensor.size, 0);
+}

package/src/formats/tokenizer/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tokenizer format module - JSON parsing utilities for tokenizer configs.
+ */
+
+export * from './types.js';

package/src/formats/tokenizer/index.js

@@ -0,0 +1,3 @@
+
+
+export * from './types.js';

package/src/formats/tokenizer/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared tokenizer/config JSON parsing utilities.
+ */
+
+export declare function parseConfigJsonText(text: string): Record<string, unknown>;
+
+export declare function parseTokenizerConfigJsonText(text: string): Record<string, unknown>;
+
+export declare function parseTokenizerJsonText(text: string): Record<string, unknown>;

package/src/formats/tokenizer/types.js

@@ -0,0 +1,22 @@
+
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`[${label}] Failed to parse JSON: ${message}`);
+  }
+}
+
+export function parseConfigJsonText(text) {
+  return parseJson(text, 'config.json');
+}
+
+export function parseTokenizerConfigJsonText(text) {
+  return parseJson(text, 'tokenizer_config.json');
+}
+
+export function parseTokenizerJsonText(text) {
+  return parseJson(text, 'tokenizer.json');
+}

package/src/generation/index.d.ts

@@ -0,0 +1,18 @@
+export { InferencePipeline, EmbeddingPipeline, createPipeline } from '../inference/pipelines/text.js';
+export { parseModelConfig, parseModelConfigFromManifest } from '../inference/pipelines/text/config.js';
+export { loadWeights, initTokenizer, isStopToken } from '../inference/pipelines/text/init.js';
+export { initTokenizerFromManifestPreset } from '../inference/pipelines/text/model-load.js';
+export {
+  StructuredJsonHeadPipeline,
+  isStructuredJsonHeadModelType,
+  createStructuredJsonHeadPipeline,
+  DreamStructuredPipeline,
+  isDreamStructuredModelType,
+  createDreamStructuredPipeline,
+} from '../inference/pipelines/structured/json-head-pipeline.js';
+
+export type { ParsedModelConfig } from '../inference/pipelines/text/config.js';
+export type { SamplingOptions } from '../inference/pipelines/text/sampling.js';
+export type { InferencePipeline, PipelineContexts, KVCacheSnapshot, LayerWeights, ExpertWeights, RouterWeights } from '../inference/pipelines/text.js';
+export type { GenerateOptions, GenerationResult } from '../inference/pipelines/text.js';
+export type { LoRAAdapter, LoRAModuleName } from '../inference/pipelines/text/lora-types.js';

package/src/generation/index.js

@@ -0,0 +1,12 @@
+export { InferencePipeline, EmbeddingPipeline, createPipeline } from '../inference/pipelines/text.js';
+export { parseModelConfig, parseModelConfigFromManifest } from '../inference/pipelines/text/config.js';
+export { loadWeights, initTokenizer, isStopToken } from '../inference/pipelines/text/init.js';
+export { initTokenizerFromManifestPreset } from '../inference/pipelines/text/model-load.js';
+export {
+  StructuredJsonHeadPipeline,
+  isStructuredJsonHeadModelType,
+  createStructuredJsonHeadPipeline,
+  DreamStructuredPipeline,
+  isDreamStructuredModelType,
+  createDreamStructuredPipeline,
+} from '../inference/pipelines/structured/json-head-pipeline.js';

package/src/gpu/command-recorder.d.ts

@@ -0,0 +1,175 @@
+/**
+ * CommandRecorder - Batched GPU Command Recording
+ *
+ * Enables recording multiple GPU operations into a single command buffer,
+ * avoiding per-kernel submit overhead. Manages temporary buffers automatically.
+ */
+
+/** Statistics about recorded operations */
+export interface RecorderStats {
+  opCount: number;
+  tempBufferCount: number;
+  pooledBufferCount: number;
+  submitted: boolean;
+}
+
+/** Options for CommandRecorder */
+export interface RecorderOptions {
+  /** Enable GPU timestamp profiling (requires 'timestamp-query' feature) */
+  profile?: boolean;
+}
+
+/** Profiling result - maps kernel label to time in milliseconds */
+export type ProfileTimings = Record<string, number>;
+
+/**
+ * CommandRecorder wraps a GPUCommandEncoder and manages temporary resources.
+ */
+export declare class CommandRecorder {
+  readonly device: GPUDevice;
+  readonly label: string;
+
+  /**
+   * @param device - GPU device (auto-detected if not provided)
+   * @param label - Label for debugging
+   * @param options - Recorder options (profiling, etc.)
+   */
+  constructor(device?: GPUDevice | null, label?: string, options?: RecorderOptions);
+
+  /**
+   * Check if profiling is enabled and available.
+   */
+  isProfilingEnabled(): boolean;
+
+  /**
+   * Create a temporary buffer that will be destroyed after submit.
+   * Use for uniform buffers and other per-operation temporaries.
+   *
+   * @param size - Buffer size in bytes
+   * @param usage - Buffer usage flags
+   * @param label - Buffer label for debugging
+   * @returns GPUBuffer
+   */
+  createTempBuffer(size: number, usage: GPUBufferUsageFlags, label?: string): GPUBuffer;
+
+  /**
+   * Create an indirect dispatch buffer initialized with workgroup counts.
+   * Buffer usage includes STORAGE so GPU kernels can update counts.
+   */
+  createIndirectDispatchBuffer(
+    workgroups?: [number, number, number] | Uint32Array,
+    label?: string
+  ): GPUBuffer;
+
+  /**
+   * Update an indirect dispatch buffer with new workgroup counts.
+   */
+  writeIndirectDispatchBuffer(
+    buffer: GPUBuffer,
+    workgroups: [number, number, number] | Uint32Array,
+    offset?: number
+  ): void;
+
+  /**
+   * Create a uniform buffer, write data, and track for cleanup.
+   * Uses content-addressed caching for identical uniform data.
+   *
+   * @param data - Data to write
+   * @param label - Buffer label
+   * @returns GPUBuffer
+   */
+  createUniformBuffer(data: ArrayBuffer | ArrayBufferView, label?: string): GPUBuffer;
+
+  /**
+   * Begin a compute pass on the encoder.
+   * When profiling is enabled, injects timestampWrites to measure GPU execution time.
+   *
+   * @param label - Pass label for debugging (used as key in profile results)
+   * @returns GPUComputePassEncoder
+   */
+  beginComputePass(label?: string): GPUComputePassEncoder;
+
+  /**
+   * Get the raw encoder for advanced use cases.
+   * @returns GPUCommandEncoder
+   */
+  getEncoder(): GPUCommandEncoder;
+
+  /**
+   * Track a buffer for cleanup after submit.
+   * Pooled buffers are released back to the pool; non-pooled buffers are destroyed.
+   *
+   * @param buffer - Buffer to clean up after submit
+   */
+  trackTemporaryBuffer(buffer: GPUBuffer): void;
+
+  /**
+   * Submit all recorded commands and clean up temporary buffers.
+   * After calling this, the recorder cannot be reused.
+   */
+  submit(): void;
+
+  /**
+   * Submit and wait for GPU to complete (useful for debugging/profiling).
+   * Also flushes the uniform cache's pending destruction queue to clean up
+   * any evicted buffers that were referenced by this command buffer.
+   * @returns Promise that resolves when GPU work is done
+   */
+  submitAndWait(): Promise<void>;
+
+  /**
+   * Get statistics about recorded operations.
+   * @returns Statistics object
+   */
+  getStats(): RecorderStats;
+
+  /**
+   * Get the submit completion latency in milliseconds (null if not resolved yet).
+   */
+  getSubmitLatencyMs(): number | null;
+
+  /**
+   * Abort recording without submitting (cleanup only).
+   * Use if an error occurs during recording.
+   */
+  abort(): void;
+
+  /**
+   * Resolve profiling timestamps and return per-kernel timings.
+   * Must be called after submit() and GPU work is done.
+   *
+   * Returns a map of kernel label to execution time in milliseconds.
+   * Labels with multiple invocations are aggregated (e.g., 'matmul' across all layers).
+   *
+   * @returns Promise resolving to timing map, or null if profiling not enabled
+   */
+  resolveProfileTimings(): Promise<ProfileTimings | null>;
+
+  /**
+   * Get a formatted profiling report.
+   * Must be called after resolveProfileTimings().
+   *
+   * @param timings - Timings from resolveProfileTimings()
+   * @returns Formatted string report
+   */
+  static formatProfileReport(timings: ProfileTimings): string;
+}
+
+/**
+ * Create a new CommandRecorder.
+ * @param label - Label for debugging
+ * @param options - Recorder options
+ * @returns CommandRecorder instance
+ */
+export function createCommandRecorder(label?: string, options?: RecorderOptions): CommandRecorder;
+
+/**
+ * Create a profiling-enabled CommandRecorder.
+ * Falls back to non-profiling if timestamp-query not available.
+ *
+ * @param label - Label for debugging
+ * @returns CommandRecorder with profiling enabled
+ */
+export function createProfilingRecorder(label?: string): CommandRecorder;
+
+export default CommandRecorder;