@simulatte/doppler 0.1.8 → 0.2.0

package/src/config/schema/kernel-registry.schema.d.ts

@@ -1,199 +0,0 @@
-/**
- * Kernel Registry Schema Definitions
- *
- * Defines the structure for kernel metadata: variants, bindings, uniforms,
- * workgroup sizes, and GPU feature requirements.
- *
- * @module config/schema/kernel-registry
- */
-
-/**
- * GPU features that a kernel variant may require.
- * These map to WebGPU adapter features.
- */
-export type GpuFeature = 'shader-f16' | 'subgroups' | 'subgroups-f16';
-
-/**
- * WebGPU buffer binding types.
- */
-export type BindingType = 'uniform' | 'storage' | 'read-only-storage';
-
-/**
- * A single buffer binding in a kernel's bind group layout.
- */
-export interface BindingSchema {
-  /** Binding index in the bind group */
-  index: number;
-
-  /** Human-readable name for debugging */
-  name: string;
-
-  /** Buffer type (uniform, storage, read-only-storage) */
-  type: BindingType;
-
-  /** Optional: whether this binding is optional (can be null) */
-  optional?: boolean;
-}
-
-/**
- * Primitive types for uniform struct fields.
- */
-export type UniformFieldType = 'u32' | 'i32' | 'f32' | 'f16';
-
-/**
- * A field in a uniform buffer struct.
- */
-export interface UniformFieldSchema {
-  /** Field name (matches WGSL struct field) */
-  name: string;
-
-  /** Data type */
-  type: UniformFieldType;
-
-  /** Byte offset in the uniform buffer */
-  offset: number;
-}
-
-/**
- * Complete uniform buffer schema for a kernel.
- */
-export interface UniformsSchema {
-  /** Total size in bytes (must be 16-byte aligned for WebGPU) */
-  size: number;
-
-  /** Fields in the uniform struct */
-  fields: UniformFieldSchema[];
-}
-
-/**
- * WGSL override constants that can be set at pipeline creation.
- */
-export interface WgslOverridesSchema {
-  [constantName: string]: number;
-}
-
-/**
- * A single kernel variant (e.g., matmul/f16, matmul/q4_fused).
- */
-export interface KernelVariantSchema {
-  /** WGSL shader filename (relative to kernels directory) */
-  wgsl: string;
-
-  /** Entry point function name in the shader */
-  entryPoint: string;
-
-  /** Workgroup size [x, y, z] */
-  workgroup: [number, number, number];
-
-  /** GPU features required to use this variant */
-  requires?: GpuFeature[];
-
-  /** Estimated shared memory usage in bytes */
-  sharedMemory?: number;
-
-  /** WGSL override constants to set at pipeline creation */
-  wgslOverrides?: WgslOverridesSchema;
-
-  /** Output data type for kernels that write F16 buffers */
-  outputDtype?: string;
-
-  /** Variant-specific metadata for dispatch planning */
-  variantMetadata?: Record<string, number | boolean | string>;
-
-  /** Additional bindings beyond the base operation bindings */
-  bindingsOverride?: BindingSchema[];
-
-  /** Override uniform schema (if different from base) */
-  uniformsOverride?: UniformsSchema;
-
-  /** Human-readable description */
-  description?: string;
-}
-
-/**
- * An operation (e.g., matmul, attention, rmsnorm) with all its variants.
- */
-export interface OperationSchema {
-  /** Base bindings shared by all variants */
-  baseBindings: BindingSchema[];
-
-  /** Base uniforms shared by all variants */
-  baseUniforms: UniformsSchema;
-
-  /** Available variants for this operation */
-  variants: Record<string, KernelVariantSchema>;
-
-  /** Human-readable description of the operation */
-  description?: string;
-}
-
-/**
- * Complete kernel registry with all operations and their variants.
- */
-export interface KernelRegistrySchema {
-  /** Schema version for compatibility checking */
-  version: string;
-
-  /** All kernel operations */
-  operations: Record<string, OperationSchema>;
-}
-
-/**
- * Fully resolved kernel configuration after merging base and variant.
- */
-export interface ResolvedKernelConfig {
-  /** Operation name */
-  operation: string;
-
-  /** Variant name */
-  variant: string;
-
-  /** WGSL shader filename */
-  wgsl: string;
-
-  /** Entry point function name */
-  entryPoint: string;
-
-  /** Workgroup size [x, y, z] */
-  workgroup: [number, number, number];
-
-  /** GPU features required */
-  requires: GpuFeature[];
-
-  /** All bindings (base + override merged) */
-  bindings: BindingSchema[];
-
-  /** Uniform schema (base or overridden) */
-  uniforms: UniformsSchema;
-
-  /** WGSL override constants */
-  wgslOverrides: WgslOverridesSchema;
-
-  /** Estimated shared memory usage in bytes */
-  sharedMemory: number;
-
-  /** Output data type for kernels that write F16 buffers */
-  outputDtype: string | null;
-
-  /** Variant-specific metadata for dispatch planning */
-  variantMetadata: Record<string, number | boolean | string> | null;
-}
-
-/**
- * Merge base and variant bindings.
- * Variant bindings with matching indices override base bindings.
- */
-export declare function mergeBindings(
-  base: BindingSchema[],
-  override?: BindingSchema[]
-): BindingSchema[];
-
-/**
- * Resolve a kernel variant to a complete configuration.
- */
-export declare function resolveKernelConfig(
-  operation: string,
-  variant: string,
-  opSchema: OperationSchema,
-  variantSchema: KernelVariantSchema
-): ResolvedKernelConfig;

package/src/config/schema/kernel-registry.schema.js

@@ -1,46 +0,0 @@
-// =============================================================================
-// Helper Functions
-// =============================================================================
-
-export function mergeBindings(
-  base,
-  override
-) {
-  if (!override || override.length === 0) {
-    return [...base];
-  }
-
-  const result = [...base];
-  for (const binding of override) {
-    const existingIdx = result.findIndex(b => b.index === binding.index);
-    if (existingIdx >= 0) {
-      result[existingIdx] = binding;
-    } else {
-      result.push(binding);
-    }
-  }
-
-  return result.sort((a, b) => a.index - b.index);
-}
-
-export function resolveKernelConfig(
-  operation,
-  variant,
-  opSchema,
-  variantSchema
-) {
-  return {
-    operation,
-    variant,
-    wgsl: variantSchema.wgsl,
-    entryPoint: variantSchema.entryPoint,
-    workgroup: variantSchema.workgroup,
-    requires: variantSchema.requires ?? [],
-    bindings: mergeBindings(opSchema.baseBindings, variantSchema.bindingsOverride),
-    uniforms: variantSchema.uniformsOverride ?? opSchema.baseUniforms,
-    wgslOverrides: variantSchema.wgslOverrides ?? {},
-    sharedMemory: variantSchema.sharedMemory ?? 0,
-    outputDtype: variantSchema.outputDtype ?? null,
-    variantMetadata: variantSchema.variantMetadata ?? null,
-  };
-}

package/src/config/schema/kernel-thresholds.schema.d.ts

@@ -1,302 +0,0 @@
-/**
- * Kernel Thresholds Schema
- *
- * Centralized configuration for kernel selection thresholds and magic numbers.
- * These values control when variant selection switches between kernel implementations.
- *
- * @module config/schema/kernel-thresholds
- */
-
-/**
- * Thresholds for matrix multiplication kernel variant selection.
- */
-export interface MatmulThresholdsSchema {
-  /**
-   * N dimension threshold for selecting multicol GEMV variants.
-   * When N >= threshold, use multicol variant for reduced workgroup count.
-   * @default 256
-   */
-  multicolThreshold: number;
-
-  /**
-   * Minimum prefill rows required before selecting the tiled f16 matmul variant.
-   * For very short prefill batches, base f16 matmul can be faster than tiled.
-   * @default 32
-   */
-  tiledPrefillMinRows: number;
-}
-
-export declare const DEFAULT_MATMUL_THRESHOLDS: MatmulThresholdsSchema;
-
-/**
- * Thresholds for RMSNorm kernel variant selection.
- */
-export interface RmsnormThresholdsSchema {
-  /**
-   * Hidden size threshold for selecting small vs default variant.
-   * When hiddenSize <= threshold, use small variant (single workgroup).
-   * @default 256
-   */
-  smallThreshold: number;
-}
-
-export declare const DEFAULT_RMSNORM_THRESHOLDS: RmsnormThresholdsSchema;
-
-/**
- * Thresholds for softmax kernel variant selection.
- */
-export interface SoftmaxThresholdsSchema {
-  /**
-   * Inner size threshold for selecting small vs default variant.
-   * When innerSize <= threshold, use small variant.
-   * @default 256
-   */
-  smallThreshold: number;
-}
-
-export declare const DEFAULT_SOFTMAX_THRESHOLDS: SoftmaxThresholdsSchema;
-
-/**
- * Thresholds for fused FFN kernel variant selection.
- */
-export interface FfnThresholdsSchema {
-  /**
-   * Intermediate size threshold for selecting multi-output variant.
-   * When intermediateSize <= threshold, use multi variant.
-   * @default 1024
-   */
-  multiOutputThreshold: number;
-}
-
-export declare const DEFAULT_FFN_THRESHOLDS: FfnThresholdsSchema;
-
-/**
- * Thresholds for sampling kernel selection.
- */
-export interface SampleThresholdsSchema {
-  /**
-   * Vocab size threshold for argmax reduce variant selection.
-   * When vocabSize > threshold, use argmax_reduce.
-   * @default 65536
-   */
-  argmaxReduceVocabThreshold: number;
-
-  /**
-   * Max topK for single-pass sampling.
-   * When topK <= threshold, use single-pass sampling.
-   * @default 100
-   */
-  singlePassTopKThreshold: number;
-}
-
-export declare const DEFAULT_SAMPLE_THRESHOLDS: SampleThresholdsSchema;
-
-/**
- * Default values for RoPE (Rotary Position Embedding) kernel.
- */
-export interface RopeDefaultsSchema {
-  /**
-   * Default theta value for RoPE frequency computation.
-   * Most models use 10000.0; some (Gemma 3) use higher values.
-   * @default 10000.0
-   */
-  defaultTheta: number;
-
-  /**
-   * Default uniform buffer size in bytes for RoPE params.
-   * @default 32
-   */
-  uniformSize: number;
-
-  /**
-   * Default start position for RoPE.
-   * @default 0
-   */
-  defaultStartPos: number;
-}
-
-export declare const DEFAULT_ROPE_DEFAULTS: RopeDefaultsSchema;
-
-/**
- * Defaults for kernel tuner limits when device limits are unavailable.
- */
-export interface TunerLimitsSchema {
-  maxComputeWorkgroupSizeX: number;
-  maxComputeWorkgroupSizeY: number;
-  maxComputeInvocationsPerWorkgroup: number;
-}
-
-export declare const DEFAULT_TUNER_LIMITS: TunerLimitsSchema;
-
-/**
- * Thresholds for attention kernel variant selection.
- */
-export interface AttentionThresholdsSchema {
-  /**
-   * Maximum KV length before switching from chunked to streaming attention.
-   * Used by decode_chunked_f16kv variant.
-   * @default 2048
-   */
-  chunkedMaxKVLen: number;
-
-  /**
-   * Minimum head dimension for chunked attention kernel eligibility.
-   * Chunked kernels require headDim >= this value.
-   * @default 128
-   */
-  minHeadDimForChunked: number;
-
-  /**
-   * Head dimension thresholds for tier selection.
-   * tier3: headDim <= 64, tier2: headDim <= 128, tier1: headDim <= 256
-   */
-  tierHeadDimLimits: {
-    tier3: number;
-    tier2: number;
-    tier1: number;
-  };
-
-  /**
-   * Minimum shared memory requirements per tier (in bytes).
-   */
-  tierMinSharedMemory: {
-    tier3: number;
-    tier2: number;
-    tier1: number;
-  };
-
-  /**
-   * Maximum head dimension for large tiled attention.
-   * @default 64
-   */
-  largeMaxHeadDim: number;
-
-  /**
-   * Maximum head dimension for small tiled attention.
-   * @default 256
-   */
-  smallMaxHeadDim: number;
-
-  /**
-   * Maximum head dimension for subgroup attention.
-   * @default 256
-   */
-  subgroupMaxHeadDim: number;
-
-  /**
-   * Shared memory requirement for large tiled attention (F32 KV).
-   * @default 20480
-   */
-  largeSharedF32: number;
-
-  /**
-   * Shared memory requirement for large tiled attention (F16 KV).
-   * @default 49152
-   */
-  largeSharedF16: number;
-
-  /**
-   * Shared memory requirement for small tiled attention (F32 KV).
-   * @default 8192
-   */
-  smallSharedF32: number;
-
-  /**
-   * Shared memory requirement for small tiled attention (F16 KV).
-   * @default 4096
-   */
-  smallSharedF16: number;
-
-  /**
-   * Shared memory requirement for subgroup attention.
-   * @default 8192
-   */
-  subgroupShared: number;
-}
-
-export declare const DEFAULT_ATTENTION_THRESHOLDS: AttentionThresholdsSchema;
-
-/**
- * Thresholds for fused matmul+norm kernel variant selection.
- */
-export interface FusedMatmulThresholdsSchema {
-  /**
-   * Maximum N dimension for "medium" (multi-column) fused variant.
-   * Beyond this, fall back to separate kernels or alternative dispatch.
-   * @default 4096
-   */
-  maxMediumN: number;
-
-  /**
-   * Maximum K dimension for fused GEMV+RMSNorm selection.
-   * When K exceeds this threshold, prefer separate kernels for better throughput.
-   * @default 8192
-   */
-  maxMediumK: number;
-
-  /**
-   * Columns per workgroup for multi-column dispatch.
-   * Each workgroup processes this many output columns.
-   * @default 4
-   */
-  colsPerWg: number;
-}
-
-export declare const DEFAULT_FUSED_MATMUL_THRESHOLDS: FusedMatmulThresholdsSchema;
-
-/**
- * Configuration for cast kernel dispatch.
- */
-export interface CastThresholdsSchema {
-  /**
-   * Maximum workgroups per dimension before falling back to 2D dispatch.
-   * @default 65535
-   */
-  maxWorkgroupsPerDim: number;
-}
-
-export declare const DEFAULT_CAST_THRESHOLDS: CastThresholdsSchema;
-
-/**
- * Bytes per element for each data type.
- */
-export declare const DTYPE_SIZES: Record<string, number>;
-
-/**
- * Get byte size for a dtype string.
- * Throws if dtype is unknown.
- */
-export declare function getDtypeSize(dtype: string): number;
-
-/**
- * All kernel thresholds in a single configuration object.
- */
-export interface KernelThresholdsConfigSchema {
-  matmul: MatmulThresholdsSchema;
-  rmsnorm: RmsnormThresholdsSchema;
-  softmax: SoftmaxThresholdsSchema;
-  ffn: FfnThresholdsSchema;
-  sample: SampleThresholdsSchema;
-  rope: RopeDefaultsSchema;
-  attention: AttentionThresholdsSchema;
-  fusedMatmul: FusedMatmulThresholdsSchema;
-  cast: CastThresholdsSchema;
-  tuner: TunerLimitsSchema;
-}
-
-export declare const DEFAULT_KERNEL_THRESHOLDS: KernelThresholdsConfigSchema;
-
-/**
- * Get the current kernel thresholds configuration.
- */
-export declare function getKernelThresholds(): KernelThresholdsConfigSchema;
-
-/**
- * Override kernel thresholds (merges with current config).
- */
-export declare function setKernelThresholds(overrides: Partial<KernelThresholdsConfigSchema>): void;
-
-/**
- * Reset kernel thresholds to defaults.
- */
-export declare function resetKernelThresholds(): void;