@holoscript/holoembed 6.1.0

package/dist/index.js

@@ -0,0 +1,567 @@
+import { ensureNodeWebGpu } from '@holoscript/snn-webgpu';
+
+// src/charTrigram.ts
+function camelSplit(s) {
+  return s.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/[^a-zA-Z0-9]+/g, " ").trim().toLowerCase();
+}
+function trigramHistogram(text, vec, offset, bins) {
+  const clean = camelSplit(text);
+  if (clean.length < 3) return;
+  const counts = new Float32Array(bins);
+  let total = 0;
+  for (let i = 0; i <= clean.length - 3; i++) {
+    const a = clean[i];
+    const b = clean[i + 1];
+    const c = clean[i + 2];
+    if (a === " " || b === " " || c === " ") continue;
+    let h = 2166136261;
+    h ^= a.charCodeAt(0);
+    h = h * 16777619 >>> 0;
+    h ^= b.charCodeAt(0);
+    h = h * 16777619 >>> 0;
+    h ^= c.charCodeAt(0);
+    h = h * 16777619 >>> 0;
+    counts[h % bins]++;
+    total++;
+  }
+  if (total > 0) {
+    for (let i = 0; i < bins; i++) {
+      vec[offset + i] = counts[i] / total;
+    }
+  }
+}
+function hashString(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = h * 16777619 >>> 0;
+  }
+  return h;
+}
+function spreadHash(hash, vec, offset, count) {
+  let state = hash;
+  for (let i = 0; i < count; i++) {
+    state = state * 1664525 + 1013904223 >>> 0;
+    vec[offset + i] = (state >>> 0) / 4294967295;
+  }
+}
+function l2Normalize(vec) {
+  let norm = 0;
+  for (let i = 0; i < vec.length; i++) norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm);
+  if (norm > 0) {
+    for (let i = 0; i < vec.length; i++) vec[i] /= norm;
+  }
+}
+var LIF_POPULATION_WGSL = (
+  /* wgsl */
+  `
+struct LIFParams {
+  tau       : f32,    // membrane time constant (ms). Default 20.0
+  vThreshold: f32,    // spike threshold (mV). Default -55.0
+  vReset    : f32,    // post-spike reset (mV). Default -75.0
+  vRest     : f32,    // resting potential (mV). Default -65.0
+  dt        : f32,    // timestep (ms). Default 1.0
+  timeSteps : u32,    // number of LIF iterations. Default 50
+  neuronCount: u32,   // number of neurons (= input dims)
+  currentScale: f32,  // scale factor for current injection. Default 240.0
+};
+
+@group(0) @binding(0) var<uniform>          params  : LIFParams;
+@group(0) @binding(1) var<storage, read>    currents: array<f32>;  // [neuronCount] in [0,1]
+@group(0) @binding(2) var<storage, read_write> rates: array<f32>;  // [neuronCount] out
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let i = gid.x;
+  if (i >= params.neuronCount) { return; }
+
+  let I_ext = currents[i] * params.currentScale; // scale to mV-equivalent current
+  var V     = params.vRest;
+  var spikes: u32 = 0u;
+
+  for (var t = 0u; t < params.timeSteps; t++) {
+    // Euler LIF: dV/dt = (vRest - V + I_ext) / tau
+    V += params.dt * (params.vRest - V + I_ext) / params.tau;
+    if (V >= params.vThreshold) {
+      V       = params.vReset;
+      spikes += 1u;
+    }
+  }
+
+  // Spike rate: fraction of timesteps with a spike
+  rates[i] = f32(spikes) / f32(params.timeSteps);
+}
+`
+);
+var DEFAULT_LIF = {
+  tau: 20,
+  vThreshold: -55,
+  vReset: -75,
+  vRest: -65,
+  dt: 1,
+  currentScale: 240
+};
+function encodeLifPopulationCpu(histogram, options = {}) {
+  const timeSteps = normalizeTimeSteps(options.timeSteps ?? 50);
+  const lif = resolveLifPopulationParams(options.lifParams);
+  const rates = new Float32Array(histogram.length);
+  for (let i = 0; i < histogram.length; i++) {
+    const input = histogram[i] ?? 0;
+    const current = input * lif.currentScale;
+    let voltage = lif.vRest;
+    let spikes = 0;
+    for (let t = 0; t < timeSteps; t++) {
+      voltage += lif.dt * (lif.vRest - voltage + current) / lif.tau;
+      if (voltage >= lif.vThreshold) {
+        voltage = lif.vReset;
+        spikes++;
+      }
+    }
+    rates[i] = spikes / timeSteps;
+  }
+  return rates;
+}
+function resolveLifPopulationParams(lifParams = {}) {
+  return { ...DEFAULT_LIF, ...lifParams };
+}
+function normalizeTimeSteps(value) {
+  if (!Number.isFinite(value) || value < 1) return 1;
+  return Math.floor(value);
+}
+var SnnAccelerator = class {
+  constructor() {
+    this._available = false;
+    this._timeSteps = 50;
+    this._lif = { ...DEFAULT_LIF };
+  }
+  // ── Public ─────────────────────────────────────────────────────────────
+  /** Whether the GPU path is active. In Node, requires the `webgpu` binding (auto-activated via ensureNodeWebGpu). */
+  get available() {
+    return this._available;
+  }
+  /**
+   * Initialize the accelerator.
+   * Detects WebGPU, compiles the LIF shader, allocates uniform buffers.
+   * Safe to call multiple times; no-op after first successful init.
+   */
+  async initialize(opts = {}, lifParams = {}) {
+    if (this._available) return;
+    this._timeSteps = normalizeTimeSteps(opts.snnTimesteps ?? 50);
+    this._lif = resolveLifPopulationParams(lifParams);
+    const enabled = opts.enableSnn !== false;
+    if (!enabled) return;
+    await ensureNodeWebGpu();
+    const gpu = globalThis.navigator?.gpu ?? globalThis.GPU;
+    if (!gpu) return;
+    try {
+      const adapter = await gpu.requestAdapter();
+      if (!adapter) return;
+      this._device = await adapter.requestDevice();
+      await this._compilePipeline();
+      this._available = true;
+    } catch {
+      this._device = void 0;
+      this._available = false;
+    }
+  }
+  /**
+   * Encode a 128-dim trigram histogram through the LIF population.
+   *
+   * Returns a 128-dim spike-rate vector.
+   * If GPU is unavailable, returns the input histogram unchanged (CPU passthrough).
+   */
+  async encode(histogram) {
+    if (!this._available || !this._device) {
+      return histogram;
+    }
+    return this._gpuEncode(histogram);
+  }
+  /**
+   * Encode a batch of histograms. Amortizes GPU round-trip cost.
+   * Falls back to sequential CPU passthrough if GPU unavailable.
+   */
+  async encodeBatch(histograms) {
+    if (!this._available || !this._device) {
+      return histograms;
+    }
+    if (histograms.length === 0) return [];
+    const n = histograms[0].length;
+    const uniform = histograms.every((h) => h.length === n);
+    if (uniform) return this._gpuEncodeBatch(histograms, n);
+    return Promise.all(histograms.map((h) => this._gpuEncode(h)));
+  }
+  /** Release GPU resources. */
+  dispose() {
+    this._paramsBuffer?.destroy();
+    this._device?.destroy();
+    this._device = void 0;
+    this._pipeline = void 0;
+    this._paramsBuffer = void 0;
+    this._available = false;
+  }
+  // ── Private ──────────────────────────────────────────────────────────────
+  async _compilePipeline() {
+    const device = this._device;
+    const module = device.createShaderModule({ code: LIF_POPULATION_WGSL });
+    this._pipeline = await device.createComputePipelineAsync({
+      layout: "auto",
+      compute: { module, entryPoint: "main" }
+    });
+    this._paramsBuffer = device.createBuffer({
+      size: 32,
+      // 8 × f32/u32
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    });
+    const paramData = new ArrayBuffer(32);
+    const f32 = new Float32Array(paramData);
+    const u32 = new Uint32Array(paramData);
+    f32[0] = this._lif.tau;
+    f32[1] = this._lif.vThreshold;
+    f32[2] = this._lif.vReset;
+    f32[3] = this._lif.vRest;
+    f32[4] = this._lif.dt;
+    u32[5] = this._timeSteps;
+    f32[7] = this._lif.currentScale;
+    device.queue.writeBuffer(this._paramsBuffer, 0, paramData);
+  }
+  async _gpuEncode(histogram) {
+    const device = this._device;
+    const pipeline = this._pipeline;
+    const paramsBuffer = this._paramsBuffer;
+    const neuronCount = histogram.length;
+    const neuronCountBuf = new Uint32Array([neuronCount]);
+    device.queue.writeBuffer(paramsBuffer, 24, neuronCountBuf);
+    const inputBuffer = device.createBuffer({
+      size: neuronCount * 4,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      mappedAtCreation: true
+    });
+    new Float32Array(inputBuffer.getMappedRange()).set(histogram);
+    inputBuffer.unmap();
+    const outputBuffer = device.createBuffer({
+      size: neuronCount * 4,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+    });
+    const stagingBuffer = device.createBuffer({
+      size: neuronCount * 4,
+      usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
+    });
+    const bindGroup = device.createBindGroup({
+      layout: pipeline.getBindGroupLayout(0),
+      entries: [
+        { binding: 0, resource: { buffer: paramsBuffer } },
+        { binding: 1, resource: { buffer: inputBuffer } },
+        { binding: 2, resource: { buffer: outputBuffer } }
+      ]
+    });
+    const encoder = device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    pass.dispatchWorkgroups(Math.ceil(neuronCount / 64));
+    pass.end();
+    encoder.copyBufferToBuffer(outputBuffer, 0, stagingBuffer, 0, neuronCount * 4);
+    device.queue.submit([encoder.finish()]);
+    await stagingBuffer.mapAsync(GPUMapMode.READ);
+    const result = new Float32Array(stagingBuffer.getMappedRange().slice(0));
+    stagingBuffer.unmap();
+    inputBuffer.destroy();
+    outputBuffer.destroy();
+    stagingBuffer.destroy();
+    return result;
+  }
+  /**
+   * Fused batch encode: M histograms of equal length N processed in a SINGLE
+   * dispatch + single readback. Because the LIF update is per-element independent,
+   * the existing shader runs unchanged over a flattened (M*N) array; each thread
+   * encodes one (histogram, neuron) pair. This removes the M x buffer-create and
+   * M x mapAsync round-trips that made the per-item path slower than CPU.
+   */
+  async _gpuEncodeBatch(histograms, n) {
+    const device = this._device;
+    const pipeline = this._pipeline;
+    const paramsBuffer = this._paramsBuffer;
+    const m = histograms.length;
+    const total = m * n;
+    device.queue.writeBuffer(paramsBuffer, 24, new Uint32Array([total]));
+    const flat = new Float32Array(total);
+    for (let j = 0; j < m; j++) flat.set(histograms[j], j * n);
+    const inputBuffer = device.createBuffer({
+      size: total * 4,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+      mappedAtCreation: true
+    });
+    new Float32Array(inputBuffer.getMappedRange()).set(flat);
+    inputBuffer.unmap();
+    const outputBuffer = device.createBuffer({
+      size: total * 4,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+    });
+    const stagingBuffer = device.createBuffer({
+      size: total * 4,
+      usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
+    });
+    const bindGroup = device.createBindGroup({
+      layout: pipeline.getBindGroupLayout(0),
+      entries: [
+        { binding: 0, resource: { buffer: paramsBuffer } },
+        { binding: 1, resource: { buffer: inputBuffer } },
+        { binding: 2, resource: { buffer: outputBuffer } }
+      ]
+    });
+    const encoder = device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    pass.dispatchWorkgroups(Math.ceil(total / 64));
+    pass.end();
+    encoder.copyBufferToBuffer(outputBuffer, 0, stagingBuffer, 0, total * 4);
+    device.queue.submit([encoder.finish()]);
+    await stagingBuffer.mapAsync(GPUMapMode.READ);
+    const all = new Float32Array(stagingBuffer.getMappedRange().slice(0));
+    stagingBuffer.unmap();
+    inputBuffer.destroy();
+    outputBuffer.destroy();
+    stagingBuffer.destroy();
+    const out = new Array(m);
+    for (let j = 0; j < m; j++) out[j] = all.slice(j * n, j * n + n);
+    return out;
+  }
+};
+
+// src/types.ts
+var HOLOEMBED_DIM = 768;
+var STRUCTURAL_DIM = 384;
+var SUBWORD_BINS = 128;
+var SUBWORD_BLOCKS = 3;
+
+// src/HoloEmbedEncoder.ts
+var KNOWN_PACKAGES = [
+  "packages/core",
+  "packages/mcp-server",
+  "packages/plugins",
+  "packages/absorb-service",
+  "packages/studio",
+  "packages/r3f-renderer"
+];
+var HoloEmbedEncoder = class {
+  constructor() {
+    this._accel = new SnnAccelerator();
+    this._snnEnabled = false;
+  }
+  /**
+   * Initialize the encoder.
+   * Attempts SNN-WebGPU setup if `enableSnn` is true (default).
+   * Falls back to CPU encoding if GPU is unavailable — always safe to await.
+   */
+  async initialize(opts = {}) {
+    await this._accel.initialize(opts);
+    this._snnEnabled = this._accel.available;
+  }
+  /** Whether the GPU SNN path is active. */
+  get snnActive() {
+    return this._snnEnabled;
+  }
+  /**
+   * Encode a symbol to a 768-dim L2-normalized Float32Array.
+   *
+   * Synchronous when SNN is disabled (CPU-only).
+   * Returns a Float32Array that can be passed to cosine-similarity search.
+   */
+  encode(sym, graph = {}) {
+    const vec = new Float32Array(HOLOEMBED_DIM);
+    this._fillStructural(vec, sym, graph);
+    this._fillSubword(vec, sym, graph);
+    l2Normalize(vec);
+    return vec;
+  }
+  /**
+   * Async encode — uses SNN population coding for the trigram blocks when GPU is active.
+   * Identical to `encode()` when GPU is unavailable.
+   */
+  async encodeAsync(sym, graph = {}) {
+    const vec = new Float32Array(HOLOEMBED_DIM);
+    this._fillStructural(vec, sym, graph);
+    if (this._snnEnabled) {
+      await this._fillSubwordSnn(vec, sym, graph);
+    } else {
+      this._fillSubword(vec, sym, graph);
+    }
+    l2Normalize(vec);
+    return vec;
+  }
+  /**
+   * Encode a plain text string to a 768-dim vector.
+   * For use with NL queries — fills the structural + name/sig trigram blocks.
+   */
+  encodeText(text) {
+    const vec = new Float32Array(HOLOEMBED_DIM);
+    this._fillStructuralFromText(vec, text);
+    trigramHistogram(text, vec, STRUCTURAL_DIM, SUBWORD_BINS);
+    l2Normalize(vec);
+    return vec;
+  }
+  /**
+   * Batch-encode text strings. Amortizes SNN GPU round-trip when GPU is active.
+   */
+  async encodeTexts(texts) {
+    if (!this._snnEnabled) {
+      return texts.map((t) => this.encodeText(t));
+    }
+    const histograms = texts.map((t) => {
+      const hist = new Float32Array(SUBWORD_BINS);
+      const tmp = new Float32Array(HOLOEMBED_DIM);
+      trigramHistogram(t, tmp, STRUCTURAL_DIM, SUBWORD_BINS);
+      hist.set(tmp.slice(STRUCTURAL_DIM, STRUCTURAL_DIM + SUBWORD_BINS));
+      return hist;
+    });
+    const snnRates = await this._accel.encodeBatch(histograms);
+    return texts.map((t, i) => {
+      const vec = new Float32Array(HOLOEMBED_DIM);
+      this._fillStructuralFromText(vec, t);
+      vec.set(snnRates[i], STRUCTURAL_DIM);
+      l2Normalize(vec);
+      return vec;
+    });
+  }
+  /** Release GPU resources. */
+  dispose() {
+    this._accel.dispose();
+  }
+  // ── Private: structural base ──────────────────────────────────────────────
+  _fillStructural(vec, sym, graph) {
+    const fp = sym.filePath.replace(/\\/g, "/");
+    for (let i = 0; i < KNOWN_PACKAGES.length; i++) {
+      vec[i] = fp.includes(KNOWN_PACKAGES[i]) ? 1 : 0;
+    }
+    vec[6] = fp.includes("__tests__") || fp.includes(".test.") || fp.includes(".spec.") ? 1 : 0;
+    vec[7] = fp.includes("/traits/") ? 1 : 0;
+    vec[8] = fp.includes("/adapters/") ? 1 : 0;
+    vec[9] = fp.includes("/providers/") ? 1 : 0;
+    const depth = (fp.match(/\//g) ?? []).length;
+    vec[10] = Math.min(depth / 8, 1);
+    spreadHash(hashString(fp), vec, 11, 117);
+    vec[128] = symbolTypeScore(sym.type);
+    vec[129] = visibilityScore(sym.visibility);
+    vec[130] = sym.isExported ? 1 : 0;
+    vec[131] = sym.signature ? Math.min(countParams(sym.signature) / 10, 1) : 0;
+    vec[132] = sym.signature?.includes(":") ? 1 : 0;
+    vec[133] = Math.min((sym.lineCount ?? 0) / 200, 1);
+    vec[134] = sym.owner ? 1 : 0;
+    spreadHash(hashString(sym.signature ?? sym.name), vec, 135, 57);
+    vec[192] = Math.min((graph.fanIn ?? 0) / 20, 1);
+    vec[193] = Math.min((graph.fanOut ?? 0) / 20, 1);
+    spreadHash(hashString(sym.docComment ?? ""), vec, 194, 62);
+    vec[256] = (graph.emitCount ?? 0) > 0 ? 1 : 0;
+    vec[257] = (graph.listenCount ?? 0) > 0 ? 1 : 0;
+    vec[258] = Math.min((graph.emitCount ?? 0) / 5, 1);
+    vec[259] = Math.min((graph.listenCount ?? 0) / 5, 1);
+    const eventKey = (graph.eventNames ?? []).sort().join("|");
+    spreadHash(hashString(eventKey), vec, 260, 60);
+    const contentKey = `${sym.type}:${sym.name}:${sym.filePath}:${sym.line}`;
+    spreadHash(hashString(contentKey), vec, 320, 64);
+  }
+  _fillStructuralFromText(vec, text) {
+    const fileMatch = /file:\s*(\S+)/i.exec(text);
+    const fp = (fileMatch?.[1] ?? "").replace(/\\/g, "/");
+    for (let i = 0; i < KNOWN_PACKAGES.length; i++) {
+      vec[i] = fp.includes(KNOWN_PACKAGES[i]) ? 1 : 0;
+    }
+    vec[6] = fp.includes("__tests__") || fp.includes(".test.") || fp.includes(".spec.") ? 1 : 0;
+    vec[7] = fp.includes("/traits/") ? 1 : 0;
+    vec[8] = fp.includes("/adapters/") ? 1 : 0;
+    vec[9] = fp.includes("/providers/") ? 1 : 0;
+    const depth = (fp.match(/\//g) ?? []).length;
+    vec[10] = Math.min(depth / 8, 1);
+    spreadHash(hashString(fp), vec, 11, 117);
+    spreadHash(hashString(text), vec, 128, 64);
+    spreadHash(hashString(text + fp), vec, 320, 64);
+  }
+  // ── Private: subword blocks (CPU) ─────────────────────────────────────────
+  _fillSubword(vec, sym, graph) {
+    trigramHistogram(
+      `${sym.name} ${sym.type} ${sym.signature ?? ""}`,
+      vec,
+      STRUCTURAL_DIM,
+      SUBWORD_BINS
+    );
+    trigramHistogram(sym.docComment ?? "", vec, STRUCTURAL_DIM + SUBWORD_BINS, SUBWORD_BINS);
+    trigramHistogram(
+      camelSplit((graph.eventNames ?? []).join(" ")),
+      vec,
+      STRUCTURAL_DIM + 2 * SUBWORD_BINS,
+      SUBWORD_BINS
+    );
+  }
+  // ── Private: subword blocks (GPU SNN) ────────────────────────────────────
+  async _fillSubwordSnn(vec, sym, graph) {
+    const h1 = new Float32Array(SUBWORD_BINS);
+    const h2 = new Float32Array(SUBWORD_BINS);
+    const h3 = new Float32Array(SUBWORD_BINS);
+    const tmp = new Float32Array(SUBWORD_BINS * 3);
+    trigramHistogram(`${sym.name} ${sym.type} ${sym.signature ?? ""}`, tmp, 0, SUBWORD_BINS);
+    trigramHistogram(sym.docComment ?? "", tmp, SUBWORD_BINS, SUBWORD_BINS);
+    trigramHistogram(
+      camelSplit((graph.eventNames ?? []).join(" ")),
+      tmp,
+      2 * SUBWORD_BINS,
+      SUBWORD_BINS
+    );
+    h1.set(tmp.slice(0, SUBWORD_BINS));
+    h2.set(tmp.slice(SUBWORD_BINS, 2 * SUBWORD_BINS));
+    h3.set(tmp.slice(2 * SUBWORD_BINS, 3 * SUBWORD_BINS));
+    const [r1, r2, r3] = await this._accel.encodeBatch([h1, h2, h3]);
+    vec.set(r1, STRUCTURAL_DIM);
+    vec.set(r2, STRUCTURAL_DIM + SUBWORD_BINS);
+    vec.set(r3, STRUCTURAL_DIM + 2 * SUBWORD_BINS);
+  }
+};
+function symbolTypeScore(type) {
+  switch (type) {
+    case "function":
+      return 1;
+    case "method":
+      return 0.9;
+    case "class":
+      return 0.7;
+    case "interface":
+      return 0.5;
+    case "type_alias":
+      return 0.4;
+    case "enum":
+      return 0.3;
+    case "constant":
+      return 0.2;
+    case "field":
+      return 0.15;
+    default:
+      return 0.1;
+  }
+}
+function visibilityScore(v) {
+  switch (v) {
+    case "public":
+      return 1;
+    case "protected":
+      return 0.5;
+    case "internal":
+      return 0.3;
+    case "private":
+      return 0;
+    default:
+      return 0.8;
+  }
+}
+function countParams(signature) {
+  const s = signature.indexOf("(");
+  const e = signature.lastIndexOf(")");
+  if (s < 0 || e <= s) return 0;
+  const inner = signature.slice(s + 1, e).trim();
+  if (!inner) return 0;
+  return inner.split(",").length;
+}
+
+export { HOLOEMBED_DIM, HoloEmbedEncoder, STRUCTURAL_DIM, SUBWORD_BINS, SUBWORD_BLOCKS, SnnAccelerator, camelSplit, encodeLifPopulationCpu, hashString, l2Normalize, spreadHash, trigramHistogram };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map