npm - @buley/neural - Versions diffs - 2.0.0 - Mend

@buley/neural 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/index.html +12 -0
package/package.json +20 -0
package/src/bench/benchmark.ts +107 -0
package/src/db/repository.test.ts +67 -0
package/src/db/repository.ts +36 -0
package/src/db/schema.ts +40 -0
package/src/engine/gpu.test.ts +120 -0
package/src/engine/gpu.ts +255 -0
package/src/engine/shaders/brain.wgsl +59 -0
package/src/engine/shaders/training.wgsl +102 -0
package/src/engine/training.test.ts +106 -0
package/src/engine/translator.test.ts +58 -0
package/src/engine/translator.ts +54 -0
package/src/index.ts +118 -0
package/src/types.ts +13 -0
package/tsconfig.json +24 -0
package/vite.config.ts +13 -0

package/index.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Neural 2.0: The Transparent Brain</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/index.ts"></script>
+  </body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,20 @@
+{
+  "name": "@buley/neural",
+  "version": "2.0.0",
+  "description": "A Transparent, Local-First, WebGPU-Accelerated Neural Graph Database.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "bench": "bun src/bench/benchmark.ts"
+  },
+  "dependencies": {
+    "@buley/dash": "^1.1.0"
+  },
+  "devDependencies": {
+    "@webgpu/types": "^0.1.69",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.0"
+  }
+}

package/src/bench/benchmark.ts ADDED Viewed

@@ -0,0 +1,107 @@
+import { GPUEngine } from "../engine/gpu";
+import { performance } from "perf_hooks";
+// Mock WebGPU types for Node environment if needed, likely handled by bun's specialized runtime or mocks if strictly node.
+// However, since we are using Bun, we might need a headless WebGPU implementation or we run this in a real browser.
+// REALITY CHECK: running WebGPU in a headless CI/Node environment usually requires 'headless-gl' or similar, but WebGPU is newer.
+// Bun does not support WebGPU native out of the box yet.
+// For this task, since the user is on Mac, we will assume they might run this via a browser test runner OR we simulate/mock for the "structure" of the benchmark
+// if actual GPU access isn't available in the terminal.
+// BUT: The roadmap implies real GPU benchmarks.
+// Strategy: We will write the benchmark to be runnable. If it fails due to missing GPU in terminal,
+// we'll note that it needs to be run in a browser context (e.g. via the web app or a test runner that supports it).
+// actually, for the purpose of this agent, I'll implement it assuming the environment *might* support it or I'll add a check.
+async function runBenchmark(label: string, networkSize: number, batchSize: number, iterations: number) {
+    console.log(`\n--- Benchmark: ${label} ---`);
+    console.log(`Network: ${networkSize} Neurons, Batch: ${batchSize}`);
+    const gpu = new GPUEngine();
+    try {
+        await gpu.init();
+    } catch (e) {
+        console.error("WebGPU Initialize Failed (Expected in non-browser env):", e);
+        return;
+    }
+    // Prepare Data
+    const weights = new Float32Array(networkSize * networkSize); // Full connectivity
+    const biases = new Float32Array(networkSize);
+    const inputs = new Float32Array(networkSize * batchSize);
+    const targets = new Float32Array(networkSize * batchSize);
+    // Init Buffers
+    const startObj = performance.now();
+    gpu.prepareBuffers(networkSize, weights, biases, batchSize);
+    gpu.prepareTrainingBuffers(targets, 0.01);
+    const initTime = performance.now() - startObj;
+    console.log(`Initialization/Upload: ${initTime.toFixed(2)}ms`);
+    // Warmup
+    await gpu.runTick(inputs);
+    // Measure Inference
+    const startInf = performance.now();
+    for (let i = 0; i < iterations; i++) {
+        await gpu.runTick(inputs);
+    }
+    const endInf = performance.now();
+    const infTime = endInf - startInf;
+    const infOPS = (iterations * batchSize) / (infTime / 1000);
+    console.log(`Inference: ${infTime.toFixed(2)}ms for ${iterations} ticks`);
+    console.log(`Throughput: ${infOPS.toFixed(0)} samples/sec`);
+    // Measure Training
+    const startTrain = performance.now();
+    for (let i = 0; i < iterations; i++) {
+        await gpu.trainTick();
+    }
+    const endTrain = performance.now();
+    const trainTime = endTrain - startTrain;
+    const trainOPS = (iterations * batchSize) / (trainTime / 1000);
+    console.log(`Training: ${trainTime.toFixed(2)}ms for ${iterations} ticks`);
+    console.log(`Throughput: ${trainOPS.toFixed(0)} samples/sec`);
+}
+async function main() {
+    // Small
+    await runBenchmark("Small", 100, 1, 100);
+    // Medium
+    await runBenchmark("Medium (Batched)", 1000, 32, 50);
+    // Large
+    await runBenchmark("Large (Batched)", 5000, 64, 20);
+}
+// Check for WebGPU polyfill or mock if running in Node without headers
+if (!global.navigator?.gpu) {
+    console.log("No WebGPU detected in global scope. Mocking for CLI structure verification...");
+    // @ts-ignore
+    global.navigator = {
+        gpu: {
+            requestAdapter: async () => ({
+                requestDevice: async () => ({
+                    createShaderModule: () => ({}),
+                    createComputePipeline: () => ({ getBindGroupLayout: () => ({}) }),
+                    createBuffer: (d: any) => ({ getMappedRange: () => new ArrayBuffer(d.size), unmap: () => {}, mapAsync: async () => {} }),
+                    createBindGroup: () => ({}),
+                    createCommandEncoder: () => ({
+                        beginComputePass: () => ({ setPipeline:()=>{}, setBindGroup:()=>{}, dispatchWorkgroups:()=>{}, end:()=>{} }),
+                        copyBufferToBuffer: ()=>{},
+                        finish: ()=>({})
+                    }),
+                    queue: { writeBuffer: ()=>{}, submit: ()=>{} }
+                })
+            })
+        }
+    };
+    // @ts-ignore
+    global.GPUBufferUsage = { STORAGE: 1, COPY_DST: 2, COPY_SRC: 4, UNIFORM: 8, MAP_READ: 16 };
+    // @ts-ignore
+    global.GPUMapMode = { READ: 1 };
+}
+main();

package/src/db/repository.test.ts ADDED Viewed

@@ -0,0 +1,67 @@
+import { expect, test, describe, mock, beforeAll } from "bun:test";
+import { NeuronRepository, SynapseRepository } from "./repository";
+// Mock @buley/dash
+const mockDash = {
+    execute: mock((query, params) => {
+        // Simple mock implementation
+        if (query.includes("INSERT")) return Promise.resolve();
+        if (query.includes("SELECT * FROM neurons")) return Promise.resolve([
+            { id: "n1", type: "input", bias: 0.1, activation: "tanh" }
+        ]);
+        if (query.includes("SELECT * FROM synapses")) return Promise.resolve([
+            { id: "s1", from_id: "n1", to_id: "n2", weight: 0.5 }
+        ]);
+        return Promise.resolve([]);
+    }),
+    addWithEmbedding: mock(() => Promise.resolve())
+};
+// Mock module
+mock.module("@buley/dash", () => ({
+    dash: mockDash
+}));
+describe("NeuronRepository", () => {
+    test("create() executes INSERT query", async () => {
+        const repo = new NeuronRepository();
+        await repo.create({ id: "n1", type: "input", bias: 0.1, activation: "tanh" });
+        expect(mockDash.execute).toHaveBeenCalled();
+        const call = mockDash.execute.mock.calls[0];
+        expect(call[0]).toContain("INSERT INTO neurons");
+        expect(call[1]).toEqual(["n1", "input", 0.1, "tanh"]);
+    });
+    test("createWithSemantics() calls addWithEmbedding", async () => {
+        const repo = new NeuronRepository();
+        await repo.createWithSemantics(
+            { id: "n2", type: "hidden", bias: 0, activation: "relu" },
+            "detects curves"
+        );
+        expect(mockDash.addWithEmbedding).toHaveBeenCalledWith("n2", "detects curves");
+    });
+    test("getAll() returns neurons", async () => {
+        mockDash.execute.mockClear();
+        const repo = new NeuronRepository();
+        const results = await repo.getAll();
+        expect(results.length).toBe(1);
+        expect(results[0].id).toBe("n1");
+    });
+});
+describe("SynapseRepository", () => {
+    test("create() executes INSERT query", async () => {
+        const repo = new SynapseRepository();
+        await repo.create({ id: "s1", from_id: "n1", to_id: "n2", weight: 0.5 });
+        expect(mockDash.execute).toHaveBeenCalled();
+        // Check latest call
+    });
+    test("getAll() returns synapses", async () => {
+        const repo = new SynapseRepository();
+        const results = await repo.getAll();
+        expect(results.length).toBe(1);
+        expect(results[0].weight).toBe(0.5);
+    });
+});

package/src/db/repository.ts ADDED Viewed

@@ -0,0 +1,36 @@
+import { dash } from "@buley/dash";
+import { Neuron, Synapse } from "../types";
+export class NeuronRepository {
+    async create(neuron: Neuron): Promise<void> {
+        await dash.execute(
+            "INSERT INTO neurons (id, type, bias, activation) VALUES (?, ?, ?, ?)",
+            [neuron.id, neuron.type, neuron.bias, neuron.activation]
+        );
+    }
+    // Feature: Add with semantic embedding
+    async createWithSemantics(neuron: Neuron, description: string): Promise<void> {
+        // We store the structured data normally
+        await this.create(neuron);
+        // And we map the ID to a semantic embedding in dash's hidden semantic store
+        await dash.addWithEmbedding(neuron.id, description);
+    }
+    async getAll(): Promise<Neuron[]> {
+        return await dash.execute("SELECT * FROM neurons") as Neuron[];
+    }
+}
+export class SynapseRepository {
+    async create(synapse: Synapse): Promise<void> {
+        await dash.execute(
+            "INSERT INTO synapses (id, from_id, to_id, weight) VALUES (?, ?, ?, ?)",
+            [synapse.id, synapse.from_id, synapse.to_id, synapse.weight]
+        );
+    }
+    async getAll(): Promise<Synapse[]> {
+        return await dash.execute("SELECT * FROM synapses") as Synapse[];
+    }
+}

package/src/db/schema.ts ADDED Viewed

@@ -0,0 +1,40 @@
+import { dash } from "@buley/dash";
+export async function initializeSchema() {
+    console.log("Initializing Neural Schema...");
+    // Neurons Table
+    // id: UUID
+    // type: input, hidden, output
+    // bias: float
+    // activation: string (tanh, relu, sigmoid)
+    await dash.execute(`
+        CREATE TABLE IF NOT EXISTS neurons (
+            id TEXT PRIMARY KEY,
+            type TEXT NOT NULL,
+            bias REAL DEFAULT 0.0,
+            activation TEXT DEFAULT 'tanh',
+            created_at INTEGER DEFAULT (unixepoch())
+        )
+    `);
+    // Synapses Table
+    // id: UUID
+    // from_id: neuron UUID
+    // to_id: neuron UUID
+    // weight: float
+    await dash.execute(`
+        CREATE TABLE IF NOT EXISTS synapses (
+            id TEXT PRIMARY KEY,
+            from_id TEXT NOT NULL,
+            to_id TEXT NOT NULL,
+            weight REAL DEFAULT 0.0,
+            created_at INTEGER DEFAULT (unixepoch()),
+            FOREIGN KEY(from_id) REFERENCES neurons(id),
+            FOREIGN KEY(to_id) REFERENCES neurons(id)
+        )
+    `);
+    console.log("Schema initialized.");
+}

package/src/engine/gpu.test.ts ADDED Viewed

@@ -0,0 +1,120 @@
+import { expect, test, describe, mock, beforeAll } from "bun:test";
+import { GPUEngine } from "./gpu";
+// Mock WebGPU Globals
+const mockDevice = {
+    createShaderModule: mock(() => ({})),
+    createComputePipeline: mock(() => ({
+        getBindGroupLayout: mock(() => ({}))
+    })),
+    createBuffer: mock((desc: any) => ({
+        getMappedRange: () => new ArrayBuffer(desc.size),
+        unmap: () => {},
+        mapAsync: async () => {}
+    })),
+    createBindGroup: mock(() => ({})),
+    createCommandEncoder: mock(() => ({
+        beginComputePass: mock(() => ({
+            setPipeline: mock(() => {}),
+            setBindGroup: mock(() => {}),
+            dispatchWorkgroups: mock(() => {}),
+            end: mock(() => {})
+        })),
+        copyBufferToBuffer: mock(() => {}),
+        finish: mock(() => ({}))
+    })),
+    queue: {
+        writeBuffer: mock(() => {}),
+        submit: mock(() => {})
+    }
+};
+const mockAdapter = {
+    requestDevice: mock(async () => mockDevice)
+};
+// Polyfill navigator.gpu
+// @ts-ignore
+global.navigator = {
+    gpu: {
+        requestAdapter: mock(async () => mockAdapter)
+    }
+};
+// Polyfill Globals
+// @ts-ignore
+global.GPUBufferUsage = {
+    MAP_READ: 1,
+    MAP_WRITE: 2,
+    COPY_SRC: 4,
+    COPY_DST: 8,
+    INDEX: 16,
+    VERTEX: 32,
+    UNIFORM: 64,
+    STORAGE: 128,
+    INDIRECT: 256,
+    QUERY_RESOLVE: 512
+};
+// @ts-ignore
+global.GPUMapMode = {
+    READ: 1,
+    WRITE: 2
+};
+describe("GPUEngine", () => {
+    test("init() requests adapter and device", async () => {
+        const gpu = new GPUEngine();
+        await gpu.init();
+        expect(navigator.gpu.requestAdapter).toHaveBeenCalled();
+        expect(mockAdapter.requestDevice).toHaveBeenCalled();
+        expect(gpu.device).toBeDefined();
+    });
+    test("prepareBuffers() creates GPU buffers", async () => {
+        const gpu = new GPUEngine();
+        await gpu.init();
+        const weights = new Float32Array([1, 2, 3, 4]);
+        const biases = new Float32Array([0, 0]);
+        gpu.prepareBuffers(2, weights, biases);
+        expect(mockDevice.createBuffer).toHaveBeenCalledTimes(5); // W, I, B, O, Uniforms
+        expect(mockDevice.createBindGroup).toHaveBeenCalled();
+    });
+    test("runTick() dispatches compute shader", async () => {
+        const gpu = new GPUEngine();
+        await gpu.init();
+        gpu.prepareBuffers(2, new Float32Array(4), new Float32Array(2));
+        const inputs = new Float32Array([1, 0]);
+        await gpu.runTick(inputs);
+        expect(mockDevice.queue.writeBuffer).toHaveBeenCalled();
+        expect(mockDevice.createCommandEncoder).toHaveBeenCalled();
+        // Check dispatch
+        // We can't easily check the nested mock calls count without storing the mock,
+        // but if no error threw, the flow worked.
+    });
+    test("prepareBuffers() and runTick() with Batch Size > 1", async () => {
+        const gpu = new GPUEngine();
+        await gpu.init();
+        const N = 4;
+        const B = 2; // Batch Size 2
+        gpu.prepareBuffers(N, new Float32Array(N), new Float32Array(N), B);
+        // Input size = N * B = 8
+        const inputs = new Float32Array(N * B);
+        await gpu.runTick(inputs);
+        expect(mockDevice.createBuffer).toHaveBeenCalled();
+        expect(mockDevice.queue.writeBuffer).toHaveBeenCalled();
+        // Verify buffer size in mock? Mock doesn't store state.
+        // But verifying it runs without throwing "Input size mismatch" proves validation worked.
+    });
+});

package/src/engine/gpu.ts ADDED Viewed

@@ -0,0 +1,255 @@
+import shaderCode from './shaders/brain.wgsl?raw';
+import trainingShaderCode from './shaders/training.wgsl?raw';
+// import trainingShaderCode from './shaders/training.wgsl?raw'; // Handled in replace block above, this is safety check
+export class GPUEngine {
+    device: GPUDevice | null = null;
+    pipeline: GPUComputePipeline | null = null;
+    bindGroup: GPUBindGroup | null = null;
+    // Training Buffers
+    deltaBuffer: GPUBuffer | null = null;
+    targetBuffer: GPUBuffer | null = null;
+    paramBuffer: GPUBuffer | null = null;
+    trainingPipeline: GPUComputePipeline | null = null;
+    deltaPipeline: GPUComputePipeline | null = null;
+    trainingBindGroup: GPUBindGroup | null = null;
+    // Buffers
+    weightBuffer: GPUBuffer | null = null;
+    inputBuffer: GPUBuffer | null = null;
+    biasBuffer: GPUBuffer | null = null;
+    outputBuffer: GPUBuffer | null = null;
+    uniformBuffer: GPUBuffer | null = null;
+    networkSize: number = 0;
+    batchSize: number = 1;
+    async init() {
+        if (!navigator.gpu) throw new Error("WebGPU not supported");
+        const adapter = await navigator.gpu.requestAdapter();
+        if (!adapter) throw new Error("No GPU adapter found");
+        this.device = await adapter.requestDevice();
+        const shaderModule = this.device.createShaderModule({ code: shaderCode });
+        const trainingModule = this.device.createShaderModule({ code: trainingShaderCode });
+        this.pipeline = this.device.createComputePipeline({
+            layout: 'auto',
+            compute: { module: shaderModule, entryPoint: 'main' }
+        });
+        this.trainingPipeline = this.device.createComputePipeline({
+            layout: 'auto',
+            compute: { module: trainingModule, entryPoint: 'update_weights' }
+        });
+        this.deltaPipeline = this.device.createComputePipeline({
+            layout: 'auto',
+            compute: { module: trainingModule, entryPoint: 'calculate_deltas' }
+        });
+        console.log("GPUEngine initialized");
+    }
+    // Prepare buffers based on network size (N) and Batch Size (B)
+    prepareBuffers(size: number, weights: Float32Array, biases: Float32Array, batchSize: number = 1) {
+        if (!this.device || !this.pipeline) throw new Error("GPUEngine not initialized");
+        this.networkSize = size;
+        this.batchSize = batchSize;
+        // Create Buffers
+        // Weights & Biases are shared (Size N or N*N)
+        this.weightBuffer = this.createBuffer(weights, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+        this.biasBuffer = this.createBuffer(biases, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+        // Inputs & Outputs are Batched (Size N * B)
+        const batchedSize = size * batchSize;
+        this.inputBuffer = this.createBuffer(new Float32Array(batchedSize), GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+        this.outputBuffer = this.createBuffer(new Float32Array(batchedSize), GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST);
+        // Dimensions Uniform: [Size, BatchSize]
+        const dimArray = new Uint32Array([size, batchSize]);
+        this.uniformBuffer = this.createBuffer(dimArray, GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+        // Bind Group
+        this.bindGroup = this.device.createBindGroup({
+            layout: this.pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: this.weightBuffer } },
+                { binding: 1, resource: { buffer: this.inputBuffer } },
+                { binding: 2, resource: { buffer: this.biasBuffer } },
+                { binding: 3, resource: { buffer: this.outputBuffer } },
+                { binding: 4, resource: { buffer: this.uniformBuffer } },
+            ]
+        });
+    }
+    private createBuffer(data: Float32Array | Uint32Array, usage: number): GPUBuffer {
+        if (!this.device) throw new Error("Device null");
+        const buffer = this.device.createBuffer({
+            size: data.byteLength,
+            usage: usage,
+            mappedAtCreation: true
+        });
+        if (data instanceof Float32Array) {
+            new Float32Array(buffer.getMappedRange()).set(data);
+        } else {
+            new Uint32Array(buffer.getMappedRange()).set(data);
+        }
+        buffer.unmap();
+        return buffer;
+    }
+    async runTick(inputs: Float32Array): Promise<Float32Array> {
+        if (!this.device || !this.pipeline || !this.bindGroup || !this.inputBuffer || !this.outputBuffer) {
+            throw new Error("GPU buffers not ready");
+        }
+        if (inputs.length !== this.networkSize * this.batchSize) {
+           throw new Error(`Input size mismatch. Expected ${this.networkSize * this.batchSize}, got ${inputs.length}`);
+        }
+        // Upload Input
+        this.device.queue.writeBuffer(this.inputBuffer, 0, inputs);
+        // Encode Command
+        const commandEncoder = this.device.createCommandEncoder();
+        const passEncoder = commandEncoder.beginComputePass();
+        passEncoder.setPipeline(this.pipeline);
+        passEncoder.setBindGroup(0, this.bindGroup);
+        // Dispatch (Size / WorkgroupSize, 1, BatchSize)
+        const workgroupSize = 64;
+        const workgroupCount = Math.ceil(this.networkSize / workgroupSize);
+        passEncoder.dispatchWorkgroups(workgroupCount, 1, this.batchSize);
+        passEncoder.end();
+        // Read Output
+        const size = inputs.byteLength;
+        const gpuReadBuffer = this.device.createBuffer({
+            size: size,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+        });
+        commandEncoder.copyBufferToBuffer(this.outputBuffer, 0, gpuReadBuffer, 0, size);
+        const gpuCommands = commandEncoder.finish();
+        this.device.queue.submit([gpuCommands]);
+        await gpuReadBuffer.mapAsync(GPUMapMode.READ);
+        const result = new Float32Array(gpuReadBuffer.getMappedRange());
+        const output = new Float32Array(result); // Copy
+        gpuReadBuffer.unmap();
+        return output;
+    }
+    prepareTrainingBuffers(targets: Float32Array, learningRate: number) {
+        if (!this.device || !this.trainingPipeline || !this.weightBuffer || !this.outputBuffer || !this.biasBuffer || !this.uniformBuffer) {
+            throw new Error("GPU not ready for training");
+        }
+        if (targets.length !== this.networkSize * this.batchSize) {
+            throw new Error(`Target size mismatch. Expected ${this.networkSize * this.batchSize}, got ${targets.length}`);
+        }
+        // Deltas & Targets are Batched (Size N * B)
+        const batchedSize = this.networkSize * this.batchSize;
+        this.deltaBuffer = this.createBuffer(new Float32Array(batchedSize), GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC);
+        this.targetBuffer = this.createBuffer(targets, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+        this.paramBuffer = this.createBuffer(new Float32Array([learningRate]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+        this.trainingBindGroup = this.device.createBindGroup({
+            layout: this.trainingPipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: this.weightBuffer } },
+                { binding: 1, resource: { buffer: this.outputBuffer } },
+                { binding: 2, resource: { buffer: this.biasBuffer } },
+                { binding: 3, resource: { buffer: this.deltaBuffer } },
+                { binding: 4, resource: { buffer: this.targetBuffer } },
+                { binding: 5, resource: { buffer: this.uniformBuffer } },
+                { binding: 6, resource: { buffer: this.paramBuffer } }
+            ]
+        });
+    }
+    private subscribers: ((event: { type: 'loss' | 'epoch', value: number }) => void)[] = [];
+    subscribe(callback: (event: { type: 'loss' | 'epoch', value: number }) => void) {
+        this.subscribers.push(callback);
+        return () => {
+            this.subscribers = this.subscribers.filter(s => s !== callback);
+        };
+    }
+    private emit(event: { type: 'loss' | 'epoch', value: number }) {
+        this.subscribers.forEach(cb => cb(event));
+    }
+    async train(inputs: Float32Array, targets: Float32Array): Promise<Float32Array> {
+        // 1. Forward Pass
+        const outputs = await this.runTick(inputs);
+        // 2. Calculate Loss (MSE) on CPU for UI Feedback
+        // Only feasible if batch size is small or we sample.
+        // For demo, we just calc full MSE.
+        let totalLoss = 0;
+        for (let i = 0; i < outputs.length; i++) {
+             // Only if target is valid? Assuming targets cover all neurons logic as per shader
+             const t = targets[i];
+             if (t > -998) {
+                 const diff = outputs[i] - t;
+                 totalLoss += 0.5 * diff * diff;
+             }
+        }
+        const meanLoss = totalLoss / this.batchSize; // Approx
+        this.emit({ type: 'loss', value: meanLoss });
+        // 3. Backward Pass
+        // Ensure buffers (deltas, targets) are ready?
+        // Reuse prepareTrainingBuffers or assume already called?
+        // Let's assume prepareTrainingBuffers was called ONCE before loop.
+        // We just need to update TARGETS buffer!
+        if (this.targetBuffer) {
+           this.device?.queue.writeBuffer(this.targetBuffer, 0, targets);
+        }
+        // Run Training Shaders
+        await this.trainTick();
+        this.emit({ type: 'epoch', value: 1 }); // Just tick count really
+        return outputs;
+    }
+    async trainTick(deltas?: Float32Array): Promise<void> {
+        if (!this.device || !this.trainingPipeline || !this.deltaPipeline || !this.trainingBindGroup || !this.deltaBuffer) {
+            throw new Error("Training not ready");
+        }
+        if (deltas && deltas.length > 0) {
+           this.device.queue.writeBuffer(this.deltaBuffer, 0, deltas);
+        }
+        const commandEncoder = this.device.createCommandEncoder();
+        const passEncoder = commandEncoder.beginComputePass();
+        // Pass 1: Calculate Deltas (Batched)
+        passEncoder.setPipeline(this.deltaPipeline);
+        passEncoder.setBindGroup(0, this.trainingBindGroup);
+        const workgroupSize = 64;
+        const workgroupCount = Math.ceil(this.networkSize / workgroupSize);
+        passEncoder.dispatchWorkgroups(workgroupCount, 1, this.batchSize);
+        passEncoder.end();
+        const updatePass = commandEncoder.beginComputePass();
+        updatePass.setPipeline(this.trainingPipeline);
+        updatePass.setBindGroup(0, this.trainingBindGroup); // Re-bind for new pass
+        updatePass.dispatchWorkgroups(workgroupCount, 1, 1); // Not batched
+        updatePass.end();
+        this.device.queue.submit([commandEncoder.finish()]);
+    }
+}

package/src/engine/shaders/brain.wgsl ADDED Viewed

@@ -0,0 +1,59 @@
+// Structure of our compute shader
+// Group 0: Bindings for data
+// Binding 0: Matrix W (Weights) - N x N flattened array
+// Binding 1: Vector X (Current Neuron Values) - N length array
+// Binding 2: Vector B (Biases) - N length array
+// Binding 3: Vector Y (Output Neuron Values) - N length array
+// Binding 4: Dimensions Uniform - Struct { size: u32 }
+struct Dimensions {
+    size: u32,
+}
+@group(0) @binding(0) var<storage, read> weights: array<f32>;
+@group(0) @binding(1) var<storage, read> input: array<f32>;
+@group(0) @binding(2) var<storage, read> biases: array<f32>;
+@group(0) @binding(3) var<storage, read_write> output: array<f32>;
+@group(0) @binding(4) var<uniform> dims: Dimensions;
+// Activation Functions
+fn tanh_approx(x: f32) -> f32 {
+    let e2x = exp(2.0 * x);
+    return (e2x - 1.0) / (e2x + 1.0);
+}
+@compute @workgroup_size(64, 1, 1)
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let row = global_id.x;
+    let batch = global_id.z;
+    let size = dims.size;
+    if (row >= size) {
+        return;
+    }
+    // Dot product: Row of W * Vector X
+    var sum: f32 = 0.0;
+    // Batch offset for input/output
+    let batch_offset = batch * size;
+    for (var col: u32 = 0u; col < size; col = col + 1u) {
+        // W is shared (not batched): weights[row * size + col]
+        let w_idx = row * size + col;
+        // Input is batched: input[batch * size + col]
+        let input_idx = batch_offset + col;
+        sum = sum + (weights[w_idx] * input[input_idx]);
+    }
+    // Add Bias (Shared)
+    sum = sum + biases[row];
+    // Activation
+    // Output is batched: output[batch * size + row]
+    let out_idx = batch_offset + row;
+    output[out_idx] = tanh_approx(sum);
+}

package/src/engine/shaders/training.wgsl ADDED Viewed

@@ -0,0 +1,102 @@
+struct Dimensions {
+    size: u32,
+    batchSize: u32,
+}
+struct TrainingParams {
+    learningRate: f32,
+}
+@group(0) @binding(0) var<storage, read_write> weights: array<f32>;
+@group(0) @binding(1) var<storage, read> values: array<f32>; // Batched Activations (N * B)
+@group(0) @binding(2) var<storage, read> biases: array<f32>;
+@group(0) @binding(3) var<storage, read_write> deltas: array<f32>; // Batched Deltas (N * B)
+@group(0) @binding(4) var<storage, read> targets: array<f32>; // Batched Targets
+@group(0) @binding(5) var<uniform> dims: Dimensions;
+@group(0) @binding(6) var<uniform> params: TrainingParams;
+fn tanh_derivative(val: f32) -> f32 {
+    return 1.0 - (val * val);
+}
+// 1. Calculate Deltas (Backward Pass) - 3D Dispatched (64, 1, B)
+@compute @workgroup_size(64, 1, 1)
+fn calculate_deltas(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let index = global_id.x;
+    let batch = global_id.z;
+    let size = dims.size;
+    if (index >= size) { return; }
+    let batch_offset = batch * size;
+    let neuron_idx = batch_offset + index;
+    let activation = values[neuron_idx];
+    let derivative = tanh_derivative(activation);
+    var error_sum: f32 = 0.0;
+    // Backpropagate error from "Next Layer" (all other neurons k)
+    // For each k (destination), we need delta_k.
+    // delta_k is also batched! deltas[batch * size + k]
+    for (var k: u32 = 0u; k < size; k = k + 1u) {
+        // Weight FROM index TO k
+        let w_idx = k * size + index;
+        let weight_ki = weights[w_idx];
+        let delta_k_idx = batch_offset + k;
+        let delta_k = deltas[delta_k_idx];
+        error_sum = error_sum + (delta_k * weight_ki);
+    }
+    // Add immediate error (MSE derivative: y - t)
+    // targets[batch * size + index]
+    let target = targets[neuron_idx];
+    if (target > -998.0) {
+        error_sum = error_sum + (activation - target);
+    }
+    deltas[neuron_idx] = error_sum * derivative;
+}
+// 2. Update Weights (Optimizer Step) - 1D Dispatched (64, 1, 1) - Accumulates Gradients over Batch
+@compute @workgroup_size(64)
+fn update_weights(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let row = global_id.x; // Target neuron
+    let size = dims.size;
+    let batch_size = dims.batchSize;
+    if (row >= size) { return; }
+    let lr = params.learningRate;
+    // Update incoming weights to this neuron 'row'
+    // W_ji (row, col)
+    for (var col: u32 = 0u; col < size; col = col + 1u) {
+        let w_idx = row * size + col;
+        // Accumulate gradient over batch
+        var gradient_sum: f32 = 0.0;
+        for (var b: u32 = 0u; b < batch_size; b = b + 1u) {
+            let batch_offset = b * size;
+            // delta_j (for this batch item)
+            let delta_j = deltas[batch_offset + row];
+            // input_i (activation of source col for this batch item)
+            let input_val = values[batch_offset + col];
+            gradient_sum = gradient_sum + (delta_j * input_val);
+        }
+        // SGD Update (Mean Gradient? Or Sum? Usually Mean for batch)
+        // Let's use Sum * (LearningRate / BatchSize) effectively, or just keep LR as is and user adjusts.
+        // Standard is Mean Gradient.
+        let mean_gradient = gradient_sum / f32(batch_size);
+        weights[w_idx] = weights[w_idx] - (lr * mean_gradient);
+    }
+}

package/src/engine/training.test.ts ADDED Viewed

@@ -0,0 +1,106 @@
+import { expect, test, describe, mock } from "bun:test";
+import { GPUEngine } from "./gpu";
+// Mock GPU globals again (copy from gpu.test.ts or import shared mock if we had one)
+// Ideally refactor mocks to a setup file. For now, inline.
+const mockDevice = {
+    createShaderModule: mock(() => ({})),
+    createComputePipeline: mock(() => ({
+        getBindGroupLayout: mock(() => ({}))
+    })),
+    createBuffer: mock((desc: any) => ({
+        getMappedRange: () => new ArrayBuffer(desc.size),
+        unmap: () => {},
+        mapAsync: async () => {}
+    })),
+    createBindGroup: mock(() => ({})),
+    createCommandEncoder: mock(() => ({
+        beginComputePass: mock(() => ({
+            setPipeline: mock(() => {}),
+            setBindGroup: mock(() => {}),
+            dispatchWorkgroups: mock(() => {}),
+            end: mock(() => {})
+        })),
+        copyBufferToBuffer: mock(() => {}),
+        finish: mock(() => ({}))
+    })),
+    queue: {
+        writeBuffer: mock(() => {}),
+        submit: mock(() => {})
+    }
+};
+const mockAdapter = {
+    requestDevice: mock(async () => mockDevice)
+};
+// @ts-ignore
+global.navigator = { gpu: { requestAdapter: mock(async () => mockAdapter) } };
+// @ts-ignore
+global.GPUBufferUsage = { STORAGE: 1, COPY_DST: 2, COPY_SRC: 4, UNIFORM: 8, MAP_READ: 16 };
+// @ts-ignore
+global.GPUMapMode = { READ: 1 };
+describe("Training Loop", () => {
+    test("prepareTrainingBuffers allocation (Batch=1)", async () => {
+        const gpu = new GPUEngine();
+        await gpu.init();
+        gpu.networkSize = 10;
+        gpu.batchSize = 1;
+        gpu.weightBuffer = {} as any;
+        gpu.outputBuffer = {} as any;
+        gpu.biasBuffer = {} as any;
+        gpu.uniformBuffer = {} as any;
+        gpu.prepareTrainingBuffers(new Float32Array(10), 0.01);
+        expect(mockDevice.createBuffer).toHaveBeenCalled();
+        expect(gpu.deltaBuffer).toBeDefined();
+        expect(gpu.targetBuffer).toBeDefined();
+    });
+    test("trainTick dispatch (Batch=1)", async () => {
+        const gpu = new GPUEngine();
+        await gpu.init();
+        gpu.networkSize = 10;
+        gpu.batchSize = 1;
+        gpu.weightBuffer = {} as any;
+        gpu.outputBuffer = {} as any;
+        gpu.biasBuffer = {} as any;
+        gpu.uniformBuffer = {} as any;
+        gpu.prepareTrainingBuffers(new Float32Array(10), 0.01);
+        await gpu.trainTick(); // Uses internal buffer/logic
+        // Should dispatch twice (Delta Calc + Weight Update)
+        // We can check calls to createCommandEncoder -> beginComputePass
+        const encoder = mockDevice.createCommandEncoder.mock.results.at(-1)?.value;
+        const pass = encoder?.beginComputePass.mock.results.at(-1)?.value;
+        // mock logic is a bit simple, let's just check overall calls
+        expect(mockDevice.queue.submit).toHaveBeenCalled();
+    });
+    test("prepareTrainingBuffers allocation (Batch=2)", async () => {
+        const gpu = new GPUEngine();
+        await gpu.init();
+        gpu.networkSize = 10;
+        gpu.batchSize = 2; // Test Batch > 1
+        gpu.weightBuffer = {} as any;
+        gpu.outputBuffer = {} as any;
+        gpu.biasBuffer = {} as any;
+        gpu.uniformBuffer = {} as any;
+        // Target size must be 20
+        gpu.prepareTrainingBuffers(new Float32Array(20), 0.01);
+        expect(mockDevice.createBuffer).toHaveBeenCalled();
+        expect(gpu.deltaBuffer).toBeDefined();
+        // Check delta buffer size? Mock doesn't store it easily accessible, but verify it didn't throw.
+    });
+});

package/src/engine/translator.test.ts ADDED Viewed

@@ -0,0 +1,58 @@
+import { expect, test, describe } from "bun:test";
+import { Translator } from "./translator";
+import { Neuron, Synapse } from "../types";
+import { mock } from "bun:test";
+mock.module("@buley/dash", () => ({
+    dash: {}
+}));
+describe("Translator", () => {
+    test("flatten() correctly converts graph to matrices", () => {
+        const translator = new Translator();
+        const neurons: Neuron[] = [
+            { id: "n1", type: "input", bias: 0.5, activation: "tanh" },
+            { id: "n2", type: "output", bias: -0.2, activation: "tanh" }
+        ];
+        const synapses: Synapse[] = [
+            // Connection n1 -> n2 (weight 0.8)
+            { id: "s1", from_id: "n1", to_id: "n2", weight: 0.8 }
+        ];
+        const result = translator.flatten(neurons, synapses);
+        expect(result.size).toBe(2);
+        // Check Biases
+        expect(result.biases[0]).toBe(0.5);
+        expect(result.biases[1]).toBeCloseTo(-0.2);
+        // Check Weights Matrix (Size 2x2 = 4 elements)
+        // Matrix is flattened: row * size + col
+        // n1 is index 0, n2 is index 1
+        // s1 is 0->1.
+        // If weights[to * size + from], then weights[1 * 2 + 0] = weights[2] should be 0.8
+        // Index 2 is row 1, col 0. (Target n2, Source n1)
+        expect(result.weights[2]).toBeCloseTo(0.8);
+        // Others should be 0
+        expect(result.weights[0]).toBe(0); // 0->0
+        expect(result.weights[1]).toBe(0); // 0->1 (n2 -> n1) - Wait, if 1*2+0=2, then 0*2+1=1.
+        // Let's re-verify my translator logic.
+        // fromIdx = 0, toIdx = 1.
+        // flatIndex = (toIdx * size) + fromIdx = (1 * 2) + 0 = 2.
+        expect(result.weights[1]).toBe(0);
+        expect(result.weights[3]).toBe(0); // 1->1
+    });
+    test("handles empty graph", () => {
+        const translator = new Translator();
+        const result = translator.flatten([], []);
+        expect(result.size).toBe(0);
+        expect(result.weights.length).toBe(0);
+    });
+});

package/src/engine/translator.ts ADDED Viewed

@@ -0,0 +1,54 @@
+import { Neuron, Synapse } from "../types";
+export class Translator {
+    // Maps Neuron logical IDs (UUIDs) to Matrix Indices (0...N)
+    private idToIndex: Map<string, number> = new Map();
+    private indexToId: string[] = [];
+    // Converts Graph -> Dense Matrices
+    flatten(neurons: Neuron[], synapses: Synapse[]): {
+        size: number,
+        weights: Float32Array,
+        biases: Float32Array,
+        initialValues: Float32Array
+    } {
+        const size = neurons.length;
+        this.idToIndex.clear();
+        this.indexToId = new Array(size);
+        // 1. Map IDs
+        neurons.forEach((n, i) => {
+            this.idToIndex.set(n.id, i);
+            this.indexToId[i] = n.id;
+        });
+        // 2. Prepare Biases & Initial Values
+        const biases = new Float32Array(size);
+        const initialValues = new Float32Array(size); // Default 0
+        neurons.forEach((n, i) => {
+            biases[i] = n.bias;
+            // initialValues could be persisted state, but defaulting to 0 for now
+        });
+        // 3. Prepare Weights Matrix (N x N)
+        // Flattened: Row-major or implementation specific.
+        // Our shader expects: weights[row * size + col]
+        // where row = target neuron, col = source neuron
+        const weights = new Float32Array(size * size);
+        synapses.forEach(s => {
+            const fromIdx = this.idToIndex.get(s.from_id);
+            const toIdx = this.idToIndex.get(s.to_id);
+            if (fromIdx !== undefined && toIdx !== undefined) {
+                // target (row) = toIdx
+                // source (col) = fromIdx
+                const flatIndex = (toIdx * size) + fromIdx;
+                weights[flatIndex] = s.weight;
+            }
+        });
+        return { size, weights, biases, initialValues };
+    }
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,118 @@
+import { dash } from "@buley/dash";
+import { initializeSchema } from "./db/schema";
+import { NeuronRepository, SynapseRepository } from "./db/repository";
+import { GPUEngine } from "./engine/gpu";
+import { Translator } from "./engine/translator";
+export class NeuralEngine {
+    gpu: GPUEngine;
+    neuronRepo: NeuronRepository;
+    synapseRepo: SynapseRepository;
+    private translator: Translator;
+    constructor() {
+        this.gpu = new GPUEngine();
+        this.neuronRepo = new NeuronRepository();
+        this.synapseRepo = new SynapseRepository();
+        this.translator = new Translator();
+    }
+    // Cache
+    private neurons: any[] = [];
+    private synapses: any[] = [];
+    async init() {
+        console.log("Neural 2.0 Engine Initializing...");
+        // 1. Persistence
+        await dash.ready();
+        await initializeSchema();
+        // 2. Compute
+        await this.gpu.init();
+        this.gpu.batchSize = 2; // Default to mini-batch of 2 for demo
+        // 3. Hydration
+        this.neurons = await this.neuronRepo.getAll();
+        this.synapses = await this.synapseRepo.getAll();
+        if (this.neurons.length === 0) {
+            console.log("Seeding test network...");
+            const n1 = "n1-" + crypto.randomUUID();
+            const n2 = "n2-" + crypto.randomUUID();
+            await this.neuronRepo.create({ id: n1, type: 'input', bias: 0, activation: 'tanh' });
+            await this.neuronRepo.create({ id: n2, type: 'output', bias: 0.5, activation: 'tanh' });
+            await this.synapseRepo.create({ id: crypto.randomUUID(), from_id: n1, to_id: n2, weight: 0.8 });
+            // Seed more for visualizer?
+            // Let's create a random cluster for demo purposes if empty
+            for(let i=0; i<50; i++) {
+                 await this.neuronRepo.create({ id: `auto-${i}`, type: 'hidden', bias: 0, activation: 'tanh' });
+            }
+            // Connect them
+            const all = await this.neuronRepo.getAll();
+            for(let i=0; i<50; i++) {
+                const s = all[Math.floor(Math.random() * all.length)].id;
+                const t = all[Math.floor(Math.random() * all.length)].id;
+                if(s!==t) await this.synapseRepo.create({ id: crypto.randomUUID(), from_id: s, to_id: t, weight: Math.random() });
+            }
+            this.neurons = await this.neuronRepo.getAll();
+            this.synapses = await this.synapseRepo.getAll();
+        }
+        // 4. Compile to GPU
+        console.log(`Compiling graph: ${this.neurons.length} neurons, ${this.synapses.length} synapses`);
+        const data = this.translator.flatten(this.neurons, this.synapses);
+        this.gpu.prepareBuffers(data.size, data.weights, data.biases, this.gpu.batchSize);
+        // Also prepare training buffers!
+        // Init target buffer with zeros
+        this.gpu.prepareTrainingBuffers(new Float32Array(data.size * this.gpu.batchSize), 0.1);
+        console.log("Engine Ready.");
+        return data;
+    }
+    getGraphData() {
+        // Map ID -> Index
+        const map = new Map<string, number>();
+        this.neurons.forEach((n, i) => map.set(n.id, i));
+        const edges = this.synapses.map(s => ({
+            id: s.id,
+            source: map.get(s.from_id) || 0,
+            target: map.get(s.to_id) || 0,
+            weight: s.weight
+        }));
+        return {
+            nodeCount: this.neurons.length,
+            edges
+        };
+    }
+    async deleteSynapse(id: string) {
+        console.log(`Lesioning synapse: ${id}`);
+        await this.synapseRepo.delete(id);
+        // Update Cache
+        this.synapses = this.synapses.filter(s => s.id !== id);
+        // Recompile (Heavy!)
+        // In a real app we'd just zero the weight in buffer
+        // But for "The Visible Brain" seeing it disappear is cooler.
+        const data = this.translator.flatten(this.neurons, this.synapses);
+        this.gpu.prepareBuffers(data.size, data.weights, data.biases, this.gpu.batchSize);
+        // Reset training buffers too to be safe/simple
+        this.gpu.prepareTrainingBuffers(new Float32Array(data.size * this.gpu.batchSize), 0.1);
+        return this.getGraphData();
+    }
+}
+// Keep a standalone init for backward compatibility or simple scripts if needed
+export async function init() {
+    const engine = new NeuralEngine();
+    return engine.init();
+}

package/src/types.ts ADDED Viewed

@@ -0,0 +1,13 @@
+export interface Neuron {
+    id: string;
+    type: 'input' | 'hidden' | 'output';
+    bias: number;
+    activation: string;
+}
+export interface Synapse {
+    id: string;
+    from_id: string;
+    to_id: string;
+    weight: number;
+}

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "types": ["@webgpu/types", "bun-types"]
+  },
+  "include": ["src"]
+}

package/vite.config.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vite';
+export default defineConfig({
+  server: {
+    headers: {
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    },
+  },
+  optimizeDeps: {
+    exclude: ['@buley/dash', '@sqlite.org/sqlite-wasm'],
+  },
+});