@simulatte/doppler 0.1.0

package/src/types/gpu.d.ts

@@ -0,0 +1,185 @@
+/**
+ * GPU and Kernel Types
+ */
+
+/** GPU device capabilities */
+export interface GpuCapabilities {
+  /** Supports shader-f16 extension */
+  hasF16: boolean;
+  /** Supports subgroups extension */
+  hasSubgroups: boolean;
+  /** Supports timestamp queries */
+  hasTimestampQuery: boolean;
+  /** Maximum buffer size */
+  maxBufferSize: number;
+  /** Maximum storage buffer binding size */
+  maxStorageBufferBindingSize: number;
+  /** Maximum compute workgroup size X */
+  maxComputeWorkgroupSizeX: number;
+  /** Maximum compute workgroup size Y */
+  maxComputeWorkgroupSizeY: number;
+  /** Maximum compute workgroup size Z */
+  maxComputeWorkgroupSizeZ: number;
+  /** Maximum compute invocations per workgroup */
+  maxComputeInvocationsPerWorkgroup: number;
+  /** Maximum compute workgroups per dimension */
+  maxComputeWorkgroupsPerDimension: number;
+  /** Subgroup size (if supported) */
+  subgroupSize?: number;
+  /** Minimum subgroup size */
+  minSubgroupSize?: number;
+  /** Maximum subgroup size */
+  maxSubgroupSize?: number;
+}
+
+/** GPU device limits */
+export interface GpuLimits {
+  maxBufferSize: number;
+  maxStorageBufferBindingSize: number;
+  maxUniformBufferBindingSize: number;
+  maxBindGroups: number;
+  maxBindingsPerBindGroup: number;
+  maxDynamicUniformBuffersPerPipelineLayout: number;
+  maxDynamicStorageBuffersPerPipelineLayout: number;
+}
+
+/** Buffer handle with metadata */
+export interface GpuBufferHandle {
+  buffer: GPUBuffer;
+  size: number;
+  usage: GPUBufferUsageFlags;
+  label?: string;
+  pooled: boolean;
+}
+
+/** Buffer allocation request */
+export interface BufferRequest {
+  size: number;
+  usage?: GPUBufferUsageFlags;
+  label?: string;
+  mappedAtCreation?: boolean;
+}
+
+/** Kernel execution mode */
+export type KernelMode = 'immediate' | 'recorded' | 'batched';
+
+/** Kernel executor interface */
+export interface KernelExecutor {
+  readonly mode: KernelMode;
+  readonly device: GPUDevice;
+
+  /** Execute a matmul operation */
+  matmul(
+    a: GPUBuffer,
+    b: GPUBuffer,
+    output: GPUBuffer,
+    m: number,
+    n: number,
+    k: number,
+    options?: MatmulOptions
+  ): void | Promise<void>;
+
+  /** Execute attention operation */
+  attention(
+    q: GPUBuffer,
+    k: GPUBuffer,
+    v: GPUBuffer,
+    output: GPUBuffer,
+    config: AttentionKernelConfig
+  ): void | Promise<void>;
+
+  /** Execute softmax operation */
+  softmax(
+    input: GPUBuffer,
+    output: GPUBuffer,
+    rows: number,
+    cols: number,
+    options?: SoftmaxOptions
+  ): void | Promise<void>;
+
+  /** Execute RMSNorm operation */
+  rmsnorm(
+    input: GPUBuffer,
+    weight: GPUBuffer,
+    output: GPUBuffer,
+    rows: number,
+    cols: number,
+    eps: number
+  ): void | Promise<void>;
+
+  /** Execute RoPE operation */
+  rope(
+    input: GPUBuffer,
+    output: GPUBuffer,
+    config: RopeKernelConfig
+  ): void | Promise<void>;
+
+  /** Submit any pending commands */
+  flush(): Promise<void>;
+}
+
+/** Matmul kernel options */
+export interface MatmulOptions {
+  transposeA?: boolean;
+  transposeB?: boolean;
+  alpha?: number;
+  beta?: number;
+  layerIdx?: number;
+}
+
+/** Attention kernel configuration */
+export interface AttentionKernelConfig {
+  batchSize: number;
+  seqLen: number;
+  numHeads: number;
+  numKVHeads: number;
+  headDim: number;
+  scale: number;
+  causal: boolean;
+  slidingWindow?: number;
+}
+
+/** Softmax kernel options */
+export interface SoftmaxOptions {
+  temperature?: number;
+  inPlace?: boolean;
+}
+
+/** RoPE kernel configuration */
+export interface RopeKernelConfig {
+  seqLen: number;
+  numHeads: number;
+  headDim: number;
+  ropeTheta: number;
+  startPos: number;
+}
+
+/** Recorded command */
+export interface RecordedCommand {
+  type: string;
+  pipeline: GPUComputePipeline;
+  bindGroup: GPUBindGroup;
+  workgroups: [number, number, number];
+}
+
+/** Command batch */
+export interface CommandBatch {
+  commands: RecordedCommand[];
+  submit(): void;
+}
+
+/** Profiling event */
+export interface ProfileEvent {
+  name: string;
+  startTime: number;
+  endTime: number;
+  duration: number;
+  metadata?: Record<string, unknown>;
+}
+
+/** Profile session */
+export interface ProfileSession {
+  events: ProfileEvent[];
+  totalDuration: number;
+  kernelBreakdown: Map<string, number>;
+}

package/src/types/gpu.js

@@ -0,0 +1,5 @@
+
+
+// This module contains only type definitions.
+// All types are exported via gpu.d.ts
+export {};

package/src/types/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './gpu.js';
+export type * from './inference.js';
+export type * from './model.js';

package/src/types/index.js

@@ -0,0 +1,3 @@
+export * from './gpu.js';
+export * from './inference.js';
+export * from './model.js';

package/src/types/inference.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Inference Pipeline Types
+ */
+
+import type { ModelConfig } from './model.js';
+
+/** Inference configuration */
+export interface InferenceConfig {
+  /** Maximum tokens to generate */
+  maxTokens: number;
+  /** Sampling temperature (0 = greedy) */
+  temperature: number;
+  /** Top-k sampling (0 = disabled) */
+  topK: number;
+  /** Top-p (nucleus) sampling */
+  topP: number;
+  /** Repetition penalty */
+  repetitionPenalty: number;
+  /** Stop sequences */
+  stopSequences?: string[];
+  /** Stop token IDs */
+  stopTokenIds?: number[];
+  /** Enable streaming */
+  stream: boolean;
+}
+
+/** Sampling configuration */
+export interface SamplingConfig {
+  temperature: number;
+  topK: number;
+  topP: number;
+  repetitionPenalty: number;
+  presencePenalty?: number;
+  frequencyPenalty?: number;
+  minP?: number;
+}
+
+/** Sampling result */
+export interface SamplingResult {
+  tokenId: number;
+  logprob: number;
+  topLogprobs?: Array<{ tokenId: number; logprob: number }>;
+}
+
+/** Generation result */
+export interface GenerationResult {
+  text: string;
+  tokens: number[];
+  finishReason: FinishReason;
+  usage: UsageStats;
+}
+
+/** Reason generation finished */
+export type FinishReason = 'stop' | 'length' | 'eos' | 'error';
+
+/** Token usage statistics */
+export interface UsageStats {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+/** Performance statistics */
+export interface PerfStats {
+  prefillTimeMs: number;
+  decodeTimeMs: number;
+  totalTimeMs: number;
+  tokensPerSecond: number;
+  prefillTokensPerSecond: number;
+  timeToFirstToken: number;
+}
+
+/** KV Cache configuration */
+export interface KVCacheConfig {
+  maxSeqLen: number;
+  numLayers: number;
+  numKVHeads: number;
+  headDim: number;
+  dtype: 'f16' | 'f32';
+  slidingWindow?: number;
+}
+
+/** KV Cache interface */
+export interface KVCache {
+  readonly config: KVCacheConfig;
+  readonly seqLen: number;
+
+  /** Get K buffer for a layer */
+  getK(layer: number): GPUBuffer;
+
+  /** Get V buffer for a layer */
+  getV(layer: number): GPUBuffer;
+
+  /** Advance sequence position */
+  advance(numTokens: number): void;
+
+  /** Reset cache */
+  reset(): void;
+
+  /** Get memory usage in bytes */
+  getMemoryUsage(): number;
+}
+
+/** MoE expert routing plan */
+export interface ExpertPlan {
+  /** Expert indices for each token [batchSize * topK] */
+  expertIndices: Uint32Array;
+  /** Routing weights for each token [batchSize * topK] */
+  weights: Float32Array;
+  /** Number of tokens routed to each expert */
+  expertCounts: Uint32Array;
+  /** Token indices sorted by expert */
+  sortedTokenIndices: Uint32Array;
+}
+
+/** MoE router configuration */
+export interface RouterConfig {
+  numExperts: number;
+  numExpertsPerToken: number;
+  routerJitter?: number;
+  capacityFactor?: number;
+}
+
+/** Tokenizer backend interface */
+export interface TokenizerBackend {
+  /** Encode text to token IDs */
+  encode(text: string): number[];
+
+  /** Decode token IDs to text */
+  decode(tokens: number[]): string;
+
+  /** Decode a single token */
+  decodeToken(tokenId: number): string;
+
+  /** Get vocabulary size */
+  vocabSize(): number;
+
+  /** Get special token IDs */
+  specialTokens(): SpecialTokens;
+}
+
+/** Special token IDs */
+export interface SpecialTokens {
+  bos?: number;
+  eos?: number;
+  pad?: number;
+  unk?: number;
+  mask?: number;
+}
+
+/** Pipeline initialization options */
+export interface PipelineOptions {
+  /** Model configuration */
+  config: ModelConfig;
+  /** GPU device */
+  device: GPUDevice;
+  /** Storage context for loading shards */
+  storage: StorageContext;
+  /** Runtime options */
+  runtime?: RuntimeOptions;
+  /** Progress callback */
+  onProgress?: ProgressCallback;
+}
+
+/** Storage context for shard loading */
+export interface StorageContext {
+  loadShard(index: number): Promise<Uint8Array>;
+}
+
+/** Runtime options */
+export interface RuntimeOptions {
+  debug?: boolean;
+  profile?: boolean;
+  kvCacheSize?: number;
+}
+
+/** Progress callback */
+export type ProgressCallback = (
+  phase: ProgressPhase,
+  progress: number,
+  detail?: string
+) => void;
+
+/** Progress phases */
+export type ProgressPhase =
+  | 'init'
+  | 'download'
+  | 'load'
+  | 'warmup'
+  | 'prefill'
+  | 'decode';
+
+/** Generation event (for streaming) */
+export type GenerationEvent =
+  | { type: 'token'; token: string; tokenId: number }
+  | { type: 'done'; result: GenerationResult }
+  | { type: 'error'; error: Error };

package/src/types/inference.js

@@ -0,0 +1,5 @@
+
+
+// This module contains only type definitions.
+// All types are exported via inference.d.ts
+export {};

package/src/types/model.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Model Configuration Types
+ */
+
+/** Supported model architectures */
+export type ModelArchitecture =
+  | 'llama'
+  | 'mistral'
+  | 'gemma'
+  | 'gemma2'
+  | 'gemma3'
+  | 'functiongemma'
+  | 'qwen2'
+  | 'qwen3'
+  | 'phi3'
+  | 'gptoss'
+  | 'gpt-oss'
+  | 'mixtral'
+  | 'deepseek'
+  | 'mamba'
+  | 'kimi_k2'
+  | 'transformer';
+
+/** Attention type variants */
+export type AttentionType = 'mha' | 'gqa' | 'mqa';
+
+/** Activation function types */
+export type ActivationType = 'silu' | 'gelu' | 'relu' | 'swiglu';
+
+/** Normalization types */
+export type NormType = 'rmsnorm' | 'layernorm';
+
+/** Position embedding types */
+export type RopeType = 'standard' | 'neox' | 'yarn' | 'dynamic';
+
+/** Core model configuration */
+export interface ModelConfig {
+  architecture: ModelArchitecture;
+  modelId: string;
+  vocabSize: number;
+  hiddenSize: number;
+  intermediateSize: number;
+  numHiddenLayers: number;
+  numAttentionHeads: number;
+  numKeyValueHeads: number;
+  headDim: number;
+  maxPositionEmbeddings: number;
+  rmsNormEps: number;
+  ropeTheta: number;
+  ropeType?: RopeType;
+  tieWordEmbeddings: boolean;
+  attentionType: AttentionType;
+  activation: ActivationType;
+  normType: NormType;
+
+  // MoE specific
+  numExperts?: number;
+  numExpertsPerToken?: number;
+  routerAux?: boolean;
+
+  // Sliding window
+  slidingWindow?: number;
+
+  // Quantization
+  quantization?: QuantizationConfig;
+}
+
+/** Quantization configuration */
+export interface QuantizationConfig {
+  format: QuantFormat;
+  bitsPerWeight: number;
+  groupSize?: number;
+  modulesToNotConvert?: string[];
+}
+
+/** Supported quantization formats */
+export type QuantFormat =
+  | 'f32'
+  | 'f16'
+  | 'bf16'
+  | 'q8_0'
+  | 'q4_0'
+  | 'q4_1'
+  | 'q4_k'
+  | 'q4_k_m'
+  | 'q5_k'
+  | 'q5_k_m'
+  | 'q6_k'
+  | 'q8_k';
+
+/** Model family detection result */
+export interface ModelFamily {
+  family: ModelArchitecture;
+  variant?: string;
+  version?: number;
+}
+
+/** Model adapter interface for architecture-specific logic */
+export interface ModelAdapter {
+  readonly family: ModelFamily;
+  readonly config: ModelConfig;
+
+  /** Get tensor name for a logical tensor */
+  getTensorName(logical: string, layer?: number): string;
+
+  /** Get layer count */
+  getLayerCount(): number;
+
+  /** Check if model uses MoE */
+  isMoE(): boolean;
+
+  /** Get attention configuration */
+  getAttentionConfig(): AttentionConfig;
+}
+
+/** Attention-specific configuration */
+export interface AttentionConfig {
+  type: AttentionType;
+  numHeads: number;
+  numKVHeads: number;
+  headDim: number;
+  scale: number;
+  slidingWindow?: number;
+  causalMask: boolean;
+}

package/src/types/model.js

@@ -0,0 +1,5 @@
+
+
+// This module contains only type definitions.
+// All types are exported via model.d.ts
+export {};

package/src/utils/index.d.ts

@@ -0,0 +1,7 @@
+// ============================================================================
+// Utilities
+// ============================================================================
+
+export { loadJson } from './load-json.js';
+export { sha256Hex } from './sha256.js';
+export { isPlainObject } from './plain-object.js';

package/src/utils/index.js

@@ -0,0 +1,7 @@
+// ============================================================================
+// Utilities
+// ============================================================================
+
+export { loadJson } from './load-json.js';
+export { sha256Hex } from './sha256.js';
+export { isPlainObject } from './plain-object.js';

package/src/utils/load-json.d.ts

@@ -0,0 +1,5 @@
+export declare function loadJson<T = unknown>(
+  resourcePath: string,
+  baseUrl?: string,
+  errorPrefix?: string
+): Promise<T>;

package/src/utils/load-json.js

@@ -0,0 +1,23 @@
+const isNodeRuntime = typeof process !== 'undefined'
+  && typeof process.versions === 'object'
+  && typeof process.versions.node === 'string';
+
+function nodeModule(specifier) {
+  return `node:${specifier}`;
+}
+
+export async function loadJson(resourcePath, baseUrl = import.meta.url, errorPrefix = 'Failed to load JSON') {
+  const resolved = new URL(resourcePath, baseUrl);
+  if (isNodeRuntime && resolved.protocol === 'file:') {
+    const fs = await import(nodeModule('fs/promises'));
+    const { fileURLToPath } = await import(nodeModule('url'));
+    const raw = await fs.readFile(fileURLToPath(resolved), 'utf-8');
+    return JSON.parse(raw);
+  }
+
+  const response = await fetch(resolved);
+  if (!response.ok) {
+    throw new Error(`${errorPrefix}: ${resourcePath}`);
+  }
+  return response.json();
+}

package/src/utils/plain-object.d.ts

@@ -0,0 +1 @@
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/src/utils/plain-object.js

@@ -0,0 +1,3 @@
+export function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/src/utils/sha256.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Return the SHA-256 hex digest for a UTF-8 string.
+ */
+export declare function sha256Hex(value: unknown): string;