@holoscript/holoembed 6.1.0

package/dist/index.d.ts

@@ -0,0 +1,321 @@
+/**
+ * HoloEmbed — shared types
+ */
+/**
+ * Minimal symbol descriptor needed for encoding.
+ * Intentionally independent of `@holoscript/absorb-service` types so this
+ * package can be used without absorb-service as a dependency.
+ */
+interface SymbolInput {
+    /** Symbol identifier (camelCase, PascalCase, snake_case). */
+    name: string;
+    /** Symbol kind: function | method | class | interface | type_alias | enum | constant | field */
+    type: string;
+    /** Absolute or root-relative file path. */
+    filePath: string;
+    /** 1-based line number. */
+    line: number;
+    /** 0-based column. */
+    column?: number;
+    /** Signature string, e.g. "function foo(x: string): void" */
+    signature?: string;
+    /** JSDoc / block-comment extracted from source. */
+    docComment?: string;
+    /** Whether the symbol is exported. */
+    isExported?: boolean;
+    /** Visibility: 'public' | 'protected' | 'private' | 'internal' */
+    visibility?: string;
+    /** Owner class/interface name (for methods/fields). */
+    owner?: string;
+    /** Lines of code. */
+    lineCount?: number;
+}
+/**
+ * Optional graph-topology features passed alongside a SymbolInput.
+ * When provided, these fill the structural call-graph and event-chain dims.
+ */
+interface GraphEnrichment {
+    /** Number of callers of this symbol. */
+    fanIn?: number;
+    /** Number of callees from this symbol. */
+    fanOut?: number;
+    /** Number of event emissions. */
+    emitCount?: number;
+    /** Number of event subscriptions. */
+    listenCount?: number;
+    /** Names of events emitted or listened to. */
+    eventNames?: string[];
+}
+interface EncoderOptions {
+    /**
+     * Whether to attempt SNN-WebGPU acceleration.
+     * Defaults to true; gracefully falls back to CPU if WebGPU is unavailable.
+     */
+    enableSnn?: boolean;
+    /**
+     * Number of LIF timesteps for SNN population coding.
+     * Higher values → richer spike-rate patterns, slower GPU batch.
+     * Default: 50 (50ms simulated at dt=1ms).
+     */
+    snnTimesteps?: number;
+}
+/** Dimensionality of the HoloEmbed output vector. */
+declare const HOLOEMBED_DIM = 768;
+/** Dimensionality of the structural base (dims 0-383). */
+declare const STRUCTURAL_DIM = 384;
+/** Number of bins per char-trigram subword block (dims 384-511, 512-639, 640-767). */
+declare const SUBWORD_BINS = 128;
+/** Number of subword blocks. */
+declare const SUBWORD_BLOCKS = 3;
+
+/**
+ * HoloEmbedEncoder — main 768-dim encoder
+ *
+ * Combines:
+ *   Dims   0–383: structural base (file topology, call-graph, event-chain)
+ *   Dims 384–511: char-trigram histogram of name + type + signature (128 bins)
+ *   Dims 512–639: char-trigram histogram of docComment (128 bins)
+ *   Dims 640–767: char-trigram histogram of event names (128 bins)
+ *
+ * Optional SNN-WebGPU population coding (Phase 2 acceleration):
+ *   Each trigram block is passed through a 128-neuron LIF population.
+ *   Output → spike-rate vector (sparse, threshold-coded) instead of raw histogram.
+ *   Falls back to raw histogram when GPU is unavailable.
+ *
+ * ## Canonical use
+ *
+ * ```ts
+ * import { HoloEmbedEncoder } from '@holoscript/holoembed';
+ *
+ * const encoder = new HoloEmbedEncoder();
+ * await encoder.initialize({ enableSnn: true }); // no-op if GPU unavailable
+ *
+ * const vec = encoder.encode(sym, { fanIn: 3, eventNames: ['pillar:spike'] });
+ * const textVec = encoder.encodeText('pillar slice emitter'); // for NL queries
+ * ```
+ *
+ * ## EmbeddingProvider integration
+ *
+ * See `HoloEmbedProvider` in `@holoscript/absorb-service` — thin wrapper that
+ * delegates to this encoder and satisfies the `EmbeddingProvider` interface.
+ */
+
+declare class HoloEmbedEncoder {
+    private _accel;
+    private _snnEnabled;
+    /**
+     * 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.
+     */
+    initialize(opts?: EncoderOptions): Promise<void>;
+    /** Whether the GPU SNN path is active. */
+    get snnActive(): boolean;
+    /**
+     * 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: SymbolInput, graph?: GraphEnrichment): Float32Array;
+    /**
+     * Async encode — uses SNN population coding for the trigram blocks when GPU is active.
+     * Identical to `encode()` when GPU is unavailable.
+     */
+    encodeAsync(sym: SymbolInput, graph?: GraphEnrichment): Promise<Float32Array>;
+    /**
+     * Encode a plain text string to a 768-dim vector.
+     * For use with NL queries — fills the structural + name/sig trigram blocks.
+     */
+    encodeText(text: string): Float32Array;
+    /**
+     * Batch-encode text strings. Amortizes SNN GPU round-trip when GPU is active.
+     */
+    encodeTexts(texts: string[]): Promise<Float32Array[]>;
+    /** Release GPU resources. */
+    dispose(): void;
+    private _fillStructural;
+    private _fillStructuralFromText;
+    private _fillSubword;
+    private _fillSubwordSnn;
+}
+
+/**
+ * SnnAccelerator — SNN-WebGPU population coding for HoloEmbed
+ *
+ * Replaces the static char-trigram histogram blocks with a richer
+ * Leaky Integrate-and-Fire population code:
+ *
+ *   Input:  128-dim normalized trigram histogram h[0..127]
+ *   Process: inject h[i] as synaptic current into LIF neuron i
+ *            simulate T timesteps at dt=1ms (default T=50)
+ *   Output: 128-dim spike-rate vector r[i] = spikes_i / T
+ *
+ * ## Why SNN population coding enriches embeddings
+ *
+ * The raw trigram histogram encodes frequency linearly: h[i] = count_i / total.
+ * The LIF population code adds a nonlinear threshold transformation:
+ *   - High-frequency trigrams (large h[i]) → many spikes → high r[i]
+ *   - Rare trigrams (small h[i]) → sub-threshold → r[i] ≈ 0
+ *
+ * This sparse representation has better cosine similarity properties than
+ * a dense histogram: two symbols with the same DOMINANT trigrams score high
+ * even if their rare-trigram distribution differs. Matches the biological
+ * precedent in Paper 33 (brain white-matter routing).
+ *
+ * ## WebGPU availability
+ *
+ * WebGPU is available in:
+ *   - Chrome 113+ / Edge 113+ (desktop)
+ *   - Node.js with the `webgpu` npm binding installed (auto-activated via ensureNodeWebGpu)
+ *
+ * In CI / Node.js without WebGPU, the accelerator reports `available = false`
+ * and returns the input histogram unchanged (CPU passthrough). No behavior
+ * difference — only performance difference for large batches.
+ *
+ * ## WGSL shader
+ *
+ * See `LIF_POPULATION_WGSL` below. One dispatch per symbol block.
+ * Workgroup size 64 → 128 neurons fit in 2 workgroups.
+ */
+
+interface LIFPopulationParams {
+    tau?: number;
+    vThreshold?: number;
+    vReset?: number;
+    vRest?: number;
+    dt?: number;
+    /** Scale factor applied to normalized trigram histogram values to produce mV-equivalent injection. */
+    currentScale?: number;
+}
+interface LIFPopulationCpuOptions {
+    /** Number of LIF timesteps. Matches EncoderOptions.snnTimesteps. */
+    timeSteps?: number;
+    /** Optional LIF parameter overrides. */
+    lifParams?: LIFPopulationParams;
+}
+/**
+ * CPU reference implementation of the LIF population coder.
+ *
+ * Production fallback remains identity passthrough so no CPU-only runtime pays
+ * for LIF simulation accidentally. Tests and benchmarks use this function as
+ * the apples-to-apples reference for the WebGPU shader.
+ */
+declare function encodeLifPopulationCpu(histogram: Float32Array, options?: LIFPopulationCpuOptions): Float32Array;
+/**
+ * SNN-WebGPU population coder for HoloEmbed trigram blocks.
+ *
+ * Usage:
+ * ```ts
+ * const accel = new SnnAccelerator();
+ * await accel.initialize({ enableSnn: true });
+ *
+ * // In embedding loop:
+ * const spikeRates = await accel.encode(trigramHistogram);
+ * ```
+ */
+declare class SnnAccelerator {
+    private _available;
+    private _timeSteps;
+    private _lif;
+    private _device?;
+    private _pipeline?;
+    private _paramsBuffer?;
+    /** Whether the GPU path is active. In Node, requires the `webgpu` binding (auto-activated via ensureNodeWebGpu). */
+    get available(): boolean;
+    /**
+     * Initialize the accelerator.
+     * Detects WebGPU, compiles the LIF shader, allocates uniform buffers.
+     * Safe to call multiple times; no-op after first successful init.
+     */
+    initialize(opts?: EncoderOptions, lifParams?: LIFPopulationParams): Promise<void>;
+    /**
+     * 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).
+     */
+    encode(histogram: Float32Array): Promise<Float32Array>;
+    /**
+     * Encode a batch of histograms. Amortizes GPU round-trip cost.
+     * Falls back to sequential CPU passthrough if GPU unavailable.
+     */
+    encodeBatch(histograms: Float32Array[]): Promise<Float32Array[]>;
+    /** Release GPU resources. */
+    dispose(): void;
+    private _compilePipeline;
+    private _gpuEncode;
+    /**
+     * 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.
+     */
+    private _gpuEncodeBatch;
+}
+
+/**
+ * charTrigram — char-trigram histogram utilities
+ *
+ * Canonical implementation for HoloEmbed subword encoding.
+ * Also used by HoloEmbedProvider in absorb-service (via copy-import pattern;
+ * absorb-service does not take @holoscript/holoembed as a dep to avoid cycles).
+ *
+ * ## Algorithm
+ *
+ * 1. camelSplit: tokenize PascalCase/camelCase/snake_case/event:names into words
+ * 2. Lowercase + strip non-alphanumeric → clean token sequence
+ * 3. Slide 3-char window over each word; skip cross-word boundaries
+ * 4. FNV-1a hash each 3-char sequence → bucket in [0, bins)
+ * 5. Normalize bucket counts by total trigram count → [0, 1] histogram
+ *
+ * ## Why char trigrams?
+ *
+ * "PillarSliceEmitter" camel-split → "pillar slice emitter"
+ *   trigrams include: "pil","ill","lla","lar" / "sli","lic","ice" / "emi","mit","itt","tte","ter"
+ *
+ * NL query "pillar slice emitter" produces IDENTICAL trigrams → perfect histogram overlap.
+ * The 128-bin FNV hash means some trigrams collide, but the overlap signal dominates for
+ * name-matched pairs.
+ *
+ * This is a BPE-lite approach: no vocabulary, no model, no training. Pure character algebra.
+ */
+/**
+ * Tokenize a camelCase / PascalCase / snake_case / colon-separated identifier
+ * into space-separated lowercase words suitable for trigram extraction.
+ *
+ * Examples:
+ *   "PillarSliceEmitter"   → "pillar slice emitter"
+ *   "extractEmitSites"     → "extract emit sites"
+ *   "ev:pillar:spike"      → "ev pillar spike"
+ *   "BRAIN_COORD_MAPPER"   → "brain coord mapper"
+ *   "pillar slice emitter" → "pillar slice emitter"  (NL query passthrough)
+ */
+declare function camelSplit(s: string): string;
+/**
+ * Accumulate a char-trigram histogram of `text` into `vec[offset..offset+bins)`.
+ *
+ * - Applies camelSplit to the input text first.
+ * - Extracts all 3-char windows that don't cross word boundaries.
+ * - FNV-1a hashes each trigram into a bin.
+ * - Normalizes by total trigram count → values in [0, 1].
+ *
+ * Note: this function does NOT L2-normalize the output; the caller does a
+ * single L2 normalization over the full output vector after all blocks are filled.
+ */
+declare function trigramHistogram(text: string, vec: Float32Array, offset: number, bins: number): void;
+/**
+ * FNV-1a 32-bit hash of a string.
+ * Used for deterministic structural feature spreading.
+ */
+declare function hashString(s: string): number;
+/**
+ * Spread a 32-bit hash deterministically into `count` dims of `vec`
+ * starting at `offset`. Each dim is in [0, 1] via LCG.
+ */
+declare function spreadHash(hash: number, vec: Float32Array, offset: number, count: number): void;
+/** In-place L2 normalization. */
+declare function l2Normalize(vec: Float32Array): void;
+
+export { type EncoderOptions, type GraphEnrichment, HOLOEMBED_DIM, HoloEmbedEncoder, type LIFPopulationCpuOptions, type LIFPopulationParams, STRUCTURAL_DIM, SUBWORD_BINS, SUBWORD_BLOCKS, SnnAccelerator, type SymbolInput, camelSplit, encodeLifPopulationCpu, hashString, l2Normalize, spreadHash, trigramHistogram };