@simulatte/doppler 0.1.8 → 0.2.0

package/src/debug/perf.js

@@ -1,51 +0,0 @@
-
-
-import { log } from './log.js';
-
-let warned = false;
-
-function warnDeprecated() {
-  if (warned) return;
-  warned = true;
-  log.warn('Perf', 'debug/perf.js is deprecated; use performance.now() or gpu/profiler.js instead.');
-}
-
-// ============================================================================
-// Performance Timing Interface
-// ============================================================================
-
-
-export const perf = {
-  marks: new Map(),
-
-  
-  mark(label) {
-    warnDeprecated();
-    this.marks.set(label, performance.now());
-  },
-
-  
-  measure(label, module = 'Perf') {
-    warnDeprecated();
-    const start = this.marks.get(label);
-    if (start === undefined) {
-      log.warn(module, `No mark found for "${label}"`);
-      return 0;
-    }
-
-    const duration = performance.now() - start;
-    this.marks.delete(label);
-    log.debug(module, `${label}: ${duration.toFixed(2)}ms`);
-    return duration;
-  },
-
-  
-  async time(label, fn) {
-    warnDeprecated();
-    const start = performance.now();
-    const result = await fn();
-    const durationMs = performance.now() - start;
-    log.debug('Perf', `${label}: ${durationMs.toFixed(2)}ms`);
-    return { result, durationMs };
-  },
-};

package/src/debug/reference/README.md

@@ -1,114 +0,0 @@
-# Reference Model Debug Scripts
-
-Purpose: PyTorch-based reference checks for validating Doppler inference outputs.
-
-## Scope
-
-- Scripted comparisons for embeddings, attention, weights, and layer outputs.
-- Debug workflow for isolating divergence sources.
-
-These scripts run the original SafeTensor model weights via PyTorch/transformers to compare against DOPPLER's quantized inference. Use these to isolate whether bugs are in DOPPLER's kernels, weight loading, or architecture implementation. They are config-only and accept a single JSON config path (no flags).
-
-## Setup
-
-```bash
-pip install torch transformers
-```
-
-## Scripts
-
-### hf_embed_check.py
-Compare embeddings and layer 0 outputs.
-
-```json
-// tmp-hf-embed.json
-{
-  "model": "google/gemma-2-2b-it",
-  "prompt": "The color of the sky is"
-}
-```
-
-```bash
-python hf_embed_check.py ./tmp-hf-embed.json
-```
-
-### hf_attn_debug.py
-Full attention debug: traces input_norm -> Q/K/V projections.
-
-```json
-// tmp-hf-attn.json
-{
-  "model": "google/gemma-2-2b-it",
-  "prompt": "The color of the sky is",
-  "layer": 0
-}
-```
-
-```bash
-python hf_attn_debug.py ./tmp-hf-attn.json
-```
-
-### hf_weights.py
-Dump Q/K/V/O projection weights for comparison.
-
-```json
-// tmp-hf-weights.json
-{
-  "model": "google/gemma-2-2b-it",
-  "layer": 0,
-  "proj": "v"
-}
-```
-
-```bash
-python hf_weights.py ./tmp-hf-weights.json
-```
-
-### hf_rope_check.py
-Verify RoPE frequencies and rotations.
-
-```json
-// tmp-hf-rope.json
-{
-  "model": "google/gemma-2-2b-it",
-  "pos": 6,
-  "dim": 256,
-  "theta": 10000.0
-}
-```
-
-```bash
-python hf_rope_check.py ./tmp-hf-rope.json
-```
-
-### hf_layer_out.py
-Compare hidden states at specific layers.
-
-```json
-// tmp-hf-layer.json
-{
-  "model": "google/gemma-2-2b-it",
-  "prompt": "The color of the sky is",
-  "layers": [0, 12, 25],
-  "token": -1
-}
-```
-
-```bash
-python hf_layer_out.py ./tmp-hf-layer.json
-```
-
-## Debugging Process
-
-1. **Identify divergence layer**: Run `hf_layer_out.py` to find where DOPPLER diverges from reference
-2. **Check embeddings**: Run `hf_embed_check.py` to verify embedding scaling
-3. **Debug attention**: Run `hf_attn_debug.py` at the diverging layer
-4. **Check weights**: Run `hf_weights.py` to compare dequantized weight values
-5. **Verify RoPE**: Run `hf_rope_check.py` if Q/K values diverge after position 0
-
-## Common Issues
-
-- **Embedding scale**: Gemma uses `sqrt(hidden_size)` scaling
-- **RMSNorm offset**: Gemma uses `(1 + weight) * x` formula
-- **Q4K dequant**: Check for repeated values (indexing bug)
-- **Attention softcapping**: Gemma 2 uses `attn_logit_soft_capping=50`

package/src/debug/reference/hf_attn_debug.py

@@ -1,114 +0,0 @@
-#!/usr/bin/env python3
-"""
-Full attention debug: traces all intermediate values through layer 0.
-
-Outputs: input_norm -> Q/K/V projections -> RoPE -> attention scores -> output
-
-Usage:
-    python hf_attn_debug.py <config.json>
-
-Config (JSON):
-    {
-      "model": "google/gemma-2-2b-it",
-      "prompt": "The color of the sky is",
-      "layer": 0
-    }
-
-Requires: pip install torch transformers
-"""
-
-import json
-import sys
-import torch
-from transformers import AutoModelForCausalLM, AutoTokenizer
-
-
-def load_config():
-    if len(sys.argv) != 2:
-        raise SystemExit("Usage: python hf_attn_debug.py <config.json>")
-    path = sys.argv[1]
-    with open(path, "r", encoding="utf-8") as handle:
-        config = json.load(handle)
-    if not isinstance(config, dict):
-        raise SystemExit("Config must be a JSON object")
-    return config
-
-
-def require_string(config, key):
-    value = config.get(key)
-    if not isinstance(value, str) or not value.strip():
-        raise SystemExit(f'Config "{key}" must be a non-empty string')
-    return value
-
-
-def require_int(config, key):
-    value = config.get(key)
-    if not isinstance(value, int):
-        raise SystemExit(f'Config "{key}" must be an integer')
-    return value
-
-
-def main():
-    config = load_config()
-    model_id = require_string(config, "model")
-    prompt = require_string(config, "prompt")
-    layer_index = require_int(config, "layer")
-
-    print(f"Loading model: {model_id}")
-    model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float32, device_map="cpu")
-    tokenizer = AutoTokenizer.from_pretrained(model_id)
-
-    inputs = tokenizer(prompt, return_tensors="pt")
-    input_ids = inputs['input_ids']
-    num_tokens = input_ids.shape[1]
-
-    print(f"\nPrompt: {prompt}")
-    print(f"Token IDs: {input_ids[0].tolist()}")
-    print(f"Num tokens: {num_tokens}")
-
-    # Get model config
-    config = model.config
-    print(f"\nModel config:")
-    print(f"  hidden_size: {config.hidden_size}")
-    print(f"  num_attention_heads: {config.num_attention_heads}")
-    print(f"  num_key_value_heads: {config.num_key_value_heads}")
-    print(f"  head_dim: {config.head_dim}")
-
-    layer = model.model.layers[layer_index]
-    attn = layer.self_attn
-
-    # Get scaled embeddings as input
-    raw_embeddings = model.model.embed_tokens(input_ids)
-    hidden_states = raw_embeddings * (config.hidden_size ** 0.5)
-    print(f"\nInput hidden states (last token first 8): {hidden_states[0, -1, :8].tolist()}")
-
-    # Apply input norm
-    normed = layer.input_layernorm(hidden_states)
-    print(f"After input_norm (last token first 8): {normed[0, -1, :8].tolist()}")
-    print(f"After input_norm (token 0 first 8): {normed[0, 0, :8].tolist()}")
-
-    # Q, K, V projections
-    with torch.no_grad():
-        q = attn.q_proj(normed)
-        k = attn.k_proj(normed)
-        v = attn.v_proj(normed)
-
-    print(f"\nQ projection (last token first 8): {q[0, -1, :8].tolist()}")
-    print(f"K projection (last token first 8): {k[0, -1, :8].tolist()}")
-    print(f"V projection (last token first 8): {v[0, -1, :8].tolist()}")
-
-    print(f"\nQ projection (token 0 first 8): {q[0, 0, :8].tolist()}")
-    print(f"K projection (token 0 first 8): {k[0, 0, :8].tolist()}")
-    print(f"V projection (token 0 first 8): {v[0, 0, :8].tolist()}")
-
-    # Check for errors vs expected
-    print(f"\nPer-token maxAbs:")
-    for t in range(num_tokens):
-        q_max = q[0, t].abs().max().item()
-        k_max = k[0, t].abs().max().item()
-        v_max = v[0, t].abs().max().item()
-        print(f"  Token {t}: Q_maxAbs={q_max:.4f}, K_maxAbs={k_max:.4f}, V_maxAbs={v_max:.4f}")
-
-
-if __name__ == "__main__":
-    main()

package/src/debug/reference/hf_embed_check.py

@@ -1,89 +0,0 @@
-#!/usr/bin/env python3
-"""
-Compare embeddings and layer outputs between HuggingFace and DOPPLER.
-
-Usage:
-    python hf_embed_check.py <config.json>
-
-Config (JSON):
-    {
-      "model": "google/gemma-2-2b-it",
-      "prompt": "The color of the sky is"
-    }
-
-Requires: pip install torch transformers
-"""
-
-import json
-import sys
-import torch
-from transformers import AutoModelForCausalLM, AutoTokenizer
-
-
-def load_config():
-    if len(sys.argv) != 2:
-        raise SystemExit("Usage: python hf_embed_check.py <config.json>")
-    path = sys.argv[1]
-    with open(path, "r", encoding="utf-8") as handle:
-        config = json.load(handle)
-    if not isinstance(config, dict):
-        raise SystemExit("Config must be a JSON object")
-    return config
-
-
-def require_string(config, key):
-    value = config.get(key)
-    if not isinstance(value, str) or not value.strip():
-        raise SystemExit(f'Config "{key}" must be a non-empty string')
-    return value
-
-
-def main():
-    config = load_config()
-    model_id = require_string(config, "model")
-    prompt = require_string(config, "prompt")
-
-    print(f"Loading model: {model_id}")
-    model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float32, device_map="cpu")
-    tokenizer = AutoTokenizer.from_pretrained(model_id)
-
-    inputs = tokenizer(prompt, return_tensors="pt")
-    input_ids = inputs['input_ids']
-
-    print(f"\nPrompt: {prompt}")
-    print(f"Token IDs: {input_ids[0].tolist()}")
-
-    # Get embeddings (raw, not scaled)
-    raw_embeddings = model.model.embed_tokens(input_ids)
-    print(f"\nRaw embeddings shape: {raw_embeddings.shape}")
-    print(f"Raw embeddings (last token first 5): {raw_embeddings[0, -1, :5].tolist()}")
-
-    # Gemma scales embeddings by sqrt(hidden_size)
-    hidden_size = model.config.hidden_size
-    scaled_embeddings = raw_embeddings * (hidden_size ** 0.5)
-    print(f"Scaled embeddings (last token first 5): {scaled_embeddings[0, -1, :5].tolist()}")
-
-    # Get layer 0 output via hooks
-    layer0_outputs = {}
-
-    def hook_layer0_output(module, input, output):
-        layer0_outputs['output'] = output[0].detach()
-
-    model.model.layers[0].register_forward_hook(hook_layer0_output)
-
-    # Run forward pass
-    with torch.no_grad():
-        outputs = model(input_ids, output_hidden_states=True)
-
-    print(f"\nLayer 0 output (last token first 5): {layer0_outputs['output'][0, -1, :5].tolist()}")
-
-    # Per-token comparison
-    print(f"\nPer-token maxAbs comparison:")
-    for t in range(inputs['input_ids'].shape[1]):
-        emb_max = scaled_embeddings[0, t].abs().max().item()
-        l0_max = layer0_outputs['output'][0, t].abs().max().item()
-        print(f"  Token {t}: emb_maxAbs={emb_max:.2f}, L0_maxAbs={l0_max:.2f}")
-
-
-if __name__ == "__main__":
-    main()

package/src/debug/reference/hf_layer_out.py

@@ -1,100 +0,0 @@
-#!/usr/bin/env python3
-"""
-Compare layer outputs at each layer between HuggingFace and DOPPLER.
-
-Usage:
-    python hf_layer_out.py <config.json>
-
-Config (JSON):
-    {
-      "model": "google/gemma-2-2b-it",
-      "prompt": "The color of the sky is",
-      "layers": [0, 12, 25],
-      "token": -1
-    }
-
-Requires: pip install torch transformers
-"""
-
-import json
-import sys
-import torch
-from transformers import AutoModelForCausalLM, AutoTokenizer
-
-
-def main():
-    if len(sys.argv) != 2:
-        raise SystemExit("Usage: python hf_layer_out.py <config.json>")
-    path = sys.argv[1]
-    with open(path, "r", encoding="utf-8") as handle:
-        config = json.load(handle)
-    if not isinstance(config, dict):
-        raise SystemExit("Config must be a JSON object")
-
-    model_id = config.get("model")
-    prompt = config.get("prompt")
-    layers = config.get("layers")
-    token = config.get("token")
-
-    if not isinstance(model_id, str) or not model_id.strip():
-        raise SystemExit('Config "model" must be a non-empty string')
-    if not isinstance(prompt, str) or not prompt.strip():
-        raise SystemExit('Config "prompt" must be a non-empty string')
-    if not isinstance(layers, list) or not layers:
-        raise SystemExit('Config "layers" must be a non-empty array')
-    if not all(isinstance(x, int) for x in layers):
-        raise SystemExit('Config "layers" entries must be integers')
-    if not isinstance(token, int):
-        raise SystemExit('Config "token" must be an integer')
-
-    layer_indices = layers
-
-    print(f"Loading model: {model_id}")
-    model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float32, device_map="cpu")
-    tokenizer = AutoTokenizer.from_pretrained(model_id)
-
-    inputs = tokenizer(prompt, return_tensors="pt")
-    input_ids = inputs['input_ids']
-    num_tokens = input_ids.shape[1]
-    token_idx = token if token >= 0 else num_tokens + token
-
-    print(f"\nPrompt: {prompt}")
-    print(f"Token IDs: {input_ids[0].tolist()}")
-    print(f"Checking token index: {token_idx}")
-
-    # Run forward pass with hidden states
-    with torch.no_grad():
-        outputs = model(input_ids, output_hidden_states=True)
-
-    hidden_states = outputs.hidden_states  # Tuple of [batch, seq, hidden]
-    print(f"\nNum hidden states: {len(hidden_states)} (embed + {len(hidden_states)-1} layers)")
-
-    for layer_idx in layer_indices:
-        if layer_idx >= len(hidden_states) - 1:
-            print(f"\nLayer {layer_idx}: OUT OF RANGE")
-            continue
-
-        # hidden_states[0] = embeddings, hidden_states[1] = layer 0 output, etc.
-        hs = hidden_states[layer_idx + 1]  # +1 because index 0 is embeddings
-
-        vals = hs[0, token_idx, :8].tolist()
-        max_abs = hs[0, token_idx].abs().max().item()
-        mean_abs = hs[0, token_idx].abs().mean().item()
-
-        print(f"\nLayer {layer_idx} output (token {token_idx}):")
-        print(f"  First 8: {[f'{v:.4f}' for v in vals]}")
-        print(f"  maxAbs: {max_abs:.4f}, meanAbs: {mean_abs:.4f}")
-
-    # Also show BOS (token 0) for comparison
-    print(f"\n--- BOS Token (position 0) for reference ---")
-    for layer_idx in layer_indices:
-        if layer_idx >= len(hidden_states) - 1:
-            continue
-        hs = hidden_states[layer_idx + 1]
-        vals = hs[0, 0, :8].tolist()
-        max_abs = hs[0, 0].abs().max().item()
-        print(f"Layer {layer_idx} (BOS): first8={[f'{v:.4f}' for v in vals]}, maxAbs={max_abs:.4f}")
-
-
-if __name__ == "__main__":
-    main()