@affectively/neural 5.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [4.1.0] - 2026-01-23
+
+- Bumped version to align with Dash 4.1.0.
+
+## [4.0.0] - 2026-01-23
+
+- **Sync Versioning**: Aligned with Dash 4.0.0 release.
+
+## [3.0.0] - 2026-01-23
+
+### Added
+
+- **Initial Release**: Scaffolded `@affectively/neural` package.
+- **Hybrid Backend**: Implemented dual-backend architecture.
+  - **WebNN**: Experimental support for NPU acceleration (`WebNNBackend`).
+  - **WebGPU**: Baseline support for GPU acceleration (`WebGPUBackend`).
+- **Factory**: Added `getBackend()` with auto-selection logic (WebNN -> WebGPU).

package/README.md

@@ -0,0 +1,32 @@
+# @affectively/neural (v3.0.0)
+
+**The "Transparent Brain" Neural Engine.**
+
+`@affectively/neural` is a high-performance, local-first neural graph engine designed to run at native speeds in the browser. It features a hybrid backend architecture that automatically leverages the best available hardware acceleration.
+
+## Features
+
+- **Hybrid Compute Engine**:
+  - **WebNN (NPU)**: Experimental support for direct Neural Processing Unit access. Use for maximum efficiency and battery life.
+  - **WebGPU (GPU)**: Baseline high-performance parallel compute using `navigator.gpu`.
+- **Auto-Selection**: Automatically detects `navigator.ml` and falls back to WebGPU if unavailable.
+- **Zero-Copy Architecture** (Planned): Shared memory buffers between storage (`@affectively/dash`) and compute.
+
+## Usage
+
+```typescript
+import { NeuralEngine } from "@affectively/neural";
+
+// Automatically initializes the best backend (WebNN -> WebGPU)
+const engine = await NeuralEngine.create();
+
+// Create a tensor
+const data = new Float32Array([1, 2, 3, 4]);
+const tensor = await engine.createTensor(data, [2, 2]);
+
+console.log("Engine running on:", engine.name);
+```
+
+## Architecture
+
+This package is part of the Neural 2.0 (now 3.0) ecosystem. It handles the _Execution_ layer, while `@affectively/dash` handles the _Representation_ (persistence) layer.

package/dist/backend/factory.d.ts

@@ -0,0 +1,7 @@
+import { ComputeBackend } from './types';
+export declare enum BackendType {
+    WebGPU = "WebGPU",
+    WebNN = "WebNN",
+    Auto = "Auto"
+}
+export declare function getBackend(type?: BackendType): Promise<ComputeBackend>;

package/dist/backend/factory.js

@@ -0,0 +1,37 @@
+import { WebGPUBackend } from './webgpu';
+import { WebNNBackend } from './webnn';
+export var BackendType;
+(function (BackendType) {
+    BackendType["WebGPU"] = "WebGPU";
+    BackendType["WebNN"] = "WebNN";
+    BackendType["Auto"] = "Auto";
+})(BackendType || (BackendType = {}));
+export async function getBackend(type = BackendType.Auto) {
+    const webnn = new WebNNBackend();
+    const webgpu = new WebGPUBackend();
+    if (type === BackendType.WebNN) {
+        await webnn.initialize();
+        return webnn;
+    }
+    if (type === BackendType.WebGPU) {
+        await webgpu.initialize();
+        return webgpu;
+    }
+    // Auto Selection Strategy:
+    // 1. Try WebNN (NPU) first for efficiency/speed
+    // 2. Fallback to WebGPU
+    // 3. (Future) Fallback to WASM
+    if (await webnn.isSupported()) {
+        try {
+            console.log('Neural 3.0: Attempting WebNN initialization...');
+            await webnn.initialize();
+            return webnn;
+        }
+        catch (err) {
+            console.warn('Neural 3.0: WebNN failed to initialize, falling back to WebGPU', err);
+        }
+    }
+    console.log('Neural 3.0: initializing WebGPU...');
+    await webgpu.initialize();
+    return webgpu;
+}

package/dist/backend/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Represents a tensor on the compute device.
+ */
+export interface Tensor {
+    /** Raw data (if downloaded to CPU) */
+    data?: Float32Array;
+    /** Shape of the tensor */
+    shape: number[];
+    /**
+     * The underlying buffer on the device.
+     * - WebGPU: GPUBuffer
+     * - WebNN: MLOperand
+     */
+    buffer?: any;
+}
+/**
+ * Abstract interface for a compute backend (WebGPU or WebNN).
+ */
+export interface ComputeBackend {
+    name: string;
+    /**
+     * Checks if this backend is supported in the current environment.
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * Initializes the backend context.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Creates a tensor from the given data.
+     */
+    createTensor(data: Float32Array, shape: number[]): Promise<Tensor>;
+}

package/dist/backend/types.js

@@ -0,0 +1 @@
+export {};

package/dist/backend/webgpu/index.d.ts

@@ -0,0 +1,9 @@
+import { ComputeBackend, Tensor } from '../types';
+export declare class WebGPUBackend implements ComputeBackend {
+    name: string;
+    private adapter;
+    private device;
+    isSupported(): Promise<boolean>;
+    initialize(): Promise<void>;
+    createTensor(data: Float32Array, shape: number[]): Promise<Tensor>;
+}

package/dist/backend/webgpu/index.js

@@ -0,0 +1,37 @@
+export class WebGPUBackend {
+    name = 'WebGPU';
+    adapter = null;
+    device = null;
+    async isSupported() {
+        return typeof navigator !== 'undefined' && 'gpu' in navigator;
+    }
+    async initialize() {
+        if (!await this.isSupported()) {
+            throw new Error('WebGPU is not supported');
+        }
+        this.adapter = await navigator.gpu.requestAdapter();
+        if (!this.adapter) {
+            throw new Error('Failed to request WebGPU adapter');
+        }
+        this.device = await this.adapter.requestDevice();
+        console.log(`WebGPU initialized: ${this.adapter.info.vendor} ${this.adapter.info.architecture}`);
+    }
+    async createTensor(data, shape) {
+        if (!this.device)
+            throw new Error('WebGPUBackend not initialized');
+        // Create a buffer for the tensor on the GPU
+        const buffer = this.device.createBuffer({
+            size: data.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+            mappedAtCreation: true
+        });
+        // Write data to the mapped buffer
+        new Float32Array(buffer.getMappedRange()).set(data);
+        buffer.unmap();
+        return {
+            data, // Keep a CPU copy for now for debugging
+            shape,
+            buffer
+        };
+    }
+}

package/dist/backend/webnn/index.d.ts

@@ -0,0 +1,14 @@
+import { ComputeBackend, Tensor } from '../types';
+declare global {
+    interface Navigator {
+        ml: any;
+    }
+}
+export declare class WebNNBackend implements ComputeBackend {
+    name: string;
+    private context;
+    private builder;
+    isSupported(): Promise<boolean>;
+    initialize(): Promise<void>;
+    createTensor(data: Float32Array, shape: number[]): Promise<Tensor>;
+}

package/dist/backend/webnn/index.js

@@ -0,0 +1,39 @@
+export class WebNNBackend {
+    name = 'WebNN';
+    context = null;
+    builder = null;
+    async isSupported() {
+        return typeof navigator !== 'undefined' && 'ml' in navigator;
+    }
+    async initialize() {
+        if (!await this.isSupported()) {
+            throw new Error('WebNN is not supported');
+        }
+        try {
+            // 1. Create Context (Access to NPU/GPU/CPU)
+            this.context = await navigator.ml.createContext();
+            // 2. Create Graph Builder (Use this to construct the compute graph)
+            this.builder = new window.MLGraphBuilder(this.context);
+            console.log('WebNN: Context initialized successfully');
+        }
+        catch (err) {
+            console.error('WebNN: Initialization failed', err);
+            throw err;
+        }
+    }
+    async createTensor(data, shape) {
+        if (!this.context)
+            throw new Error('WebNNBackend not initialized');
+        // In WebNN, we often bind data at execution time rather than uploading strictly beforehand
+        // But for the abstraction, we can treat constant data as inputs.
+        // For now, return the CPU data, and we will bind it as an MLBuffer or Input/Constant during graph execution.
+        // Note: WebNN currently deals in Operations. 
+        // Data is usually an input to the `compute` method.
+        // We will store the Float32Array as the "buffer" for now.
+        return {
+            data,
+            shape,
+            buffer: data // Holding the reference for now
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './backend/types';
+export * from './backend/factory';
+export * from './backend/webgpu';
+export * from './backend/webnn';
+export declare class NeuralEngine {
+    static create(): Promise<import(".").ComputeBackend>;
+}

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from './backend/types';
+export * from './backend/factory';
+export * from './backend/webgpu';
+export * from './backend/webnn';
+// Re-export specific classes if needed for direct access
+import { getBackend } from './backend/factory';
+export class NeuralEngine {
+    // Placeholder for the high-level engine that uses the backend
+    static async create() {
+        return getBackend();
+    }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@affectively/neural",
+  "version": "5.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@webgpu/types": "^0.1.69",
+    "typescript": "^5.0.0"
+  }
+}

package/src/backend/factory.ts

@@ -0,0 +1,43 @@
+import { ComputeBackend } from './types';
+import { WebGPUBackend } from './webgpu';
+import { WebNNBackend } from './webnn';
+
+export enum BackendType {
+  WebGPU = 'WebGPU',
+  WebNN = 'WebNN',
+  Auto = 'Auto'
+}
+
+export async function getBackend(type: BackendType = BackendType.Auto): Promise<ComputeBackend> {
+  const webnn = new WebNNBackend();
+  const webgpu = new WebGPUBackend();
+
+  if (type === BackendType.WebNN) {
+    await webnn.initialize();
+    return webnn;
+  }
+
+  if (type === BackendType.WebGPU) {
+    await webgpu.initialize();
+    return webgpu;
+  }
+
+  // Auto Selection Strategy:
+  // 1. Try WebNN (NPU) first for efficiency/speed
+  // 2. Fallback to WebGPU
+  // 3. (Future) Fallback to WASM
+  
+  if (await webnn.isSupported()) {
+    try {
+      console.log('Neural 3.0: Attempting WebNN initialization...');
+      await webnn.initialize();
+      return webnn;
+    } catch (err) {
+      console.warn('Neural 3.0: WebNN failed to initialize, falling back to WebGPU', err);
+    }
+  }
+
+  console.log('Neural 3.0: initializing WebGPU...');
+  await webgpu.initialize();
+  return webgpu;
+}

package/src/backend/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Represents a tensor on the compute device.
+ */
+export interface Tensor {
+  /** Raw data (if downloaded to CPU) */
+  data?: Float32Array;
+  /** Shape of the tensor */
+  shape: number[];
+  /** 
+   * The underlying buffer on the device.
+   * - WebGPU: GPUBuffer
+   * - WebNN: MLOperand
+   */
+  buffer?: any; 
+}
+
+/**
+ * Abstract interface for a compute backend (WebGPU or WebNN).
+ */
+export interface ComputeBackend {
+  name: string;
+  
+  /**
+   * Checks if this backend is supported in the current environment.
+   */
+  isSupported(): Promise<boolean>;
+
+  /**
+   * Initializes the backend context.
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Creates a tensor from the given data.
+   */
+  createTensor(data: Float32Array, shape: number[]): Promise<Tensor>;
+  
+  // Future operators will be added here (matmul, add, etc.)
+}

package/src/backend/webgpu/index.ts

@@ -0,0 +1,46 @@
+import { ComputeBackend, Tensor } from '../types';
+
+export class WebGPUBackend implements ComputeBackend {
+  name = 'WebGPU';
+  private adapter: GPUAdapter | null = null;
+  private device: GPUDevice | null = null;
+
+  async isSupported(): Promise<boolean> {
+    return typeof navigator !== 'undefined' && 'gpu' in navigator;
+  }
+
+  async initialize(): Promise<void> {
+    if (!await this.isSupported()) {
+      throw new Error('WebGPU is not supported');
+    }
+
+    this.adapter = await navigator.gpu.requestAdapter();
+    if (!this.adapter) {
+      throw new Error('Failed to request WebGPU adapter');
+    }
+
+    this.device = await this.adapter.requestDevice();
+    console.log(`WebGPU initialized: ${this.adapter.info.vendor} ${this.adapter.info.architecture}`);
+  }
+
+  async createTensor(data: Float32Array, shape: number[]): Promise<Tensor> {
+    if (!this.device) throw new Error('WebGPUBackend not initialized');
+
+    // Create a buffer for the tensor on the GPU
+    const buffer = this.device.createBuffer({
+      size: data.byteLength,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+      mappedAtCreation: true
+    });
+
+    // Write data to the mapped buffer
+    new Float32Array(buffer.getMappedRange()).set(data);
+    buffer.unmap();
+
+    return {
+      data, // Keep a CPU copy for now for debugging
+      shape,
+      buffer
+    };
+  }
+}

package/src/backend/webnn/index.ts

@@ -0,0 +1,55 @@
+import { ComputeBackend, Tensor } from '../types';
+
+// Augment the navigator interface for WebNN (types might be missing in default libs)
+declare global {
+  interface Navigator {
+    ml: any;
+  }
+}
+
+export class WebNNBackend implements ComputeBackend {
+  name = 'WebNN';
+  private context: any = null;
+  private builder: any = null;
+
+  async isSupported(): Promise<boolean> {
+    return typeof navigator !== 'undefined' && 'ml' in navigator;
+  }
+
+  async initialize(): Promise<void> {
+    if (!await this.isSupported()) {
+      throw new Error('WebNN is not supported');
+    }
+
+    try {
+      // 1. Create Context (Access to NPU/GPU/CPU)
+      this.context = await navigator.ml.createContext();
+      
+      // 2. Create Graph Builder (Use this to construct the compute graph)
+      this.builder = new (window as any).MLGraphBuilder(this.context);
+      
+      console.log('WebNN: Context initialized successfully');
+    } catch (err) {
+      console.error('WebNN: Initialization failed', err);
+      throw err;
+    }
+  }
+
+  async createTensor(data: Float32Array, shape: number[]): Promise<Tensor> {
+    if (!this.context) throw new Error('WebNNBackend not initialized');
+
+    // In WebNN, we often bind data at execution time rather than uploading strictly beforehand
+    // But for the abstraction, we can treat constant data as inputs.
+    // For now, return the CPU data, and we will bind it as an MLBuffer or Input/Constant during graph execution.
+    
+    // Note: WebNN currently deals in Operations. 
+    // Data is usually an input to the `compute` method.
+    // We will store the Float32Array as the "buffer" for now.
+    
+    return {
+      data,
+      shape,
+      buffer: data // Holding the reference for now
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from './backend/types';
+export * from './backend/factory';
+export * from './backend/webgpu';
+export * from './backend/webnn';
+
+// Re-export specific classes if needed for direct access
+import { getBackend } from './backend/factory';
+
+export class NeuralEngine {
+  // Placeholder for the high-level engine that uses the backend
+  static async create() {
+    return getBackend();
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["ESNext", "DOM"],
+    "types": ["@webgpu/types"]
+  },
+  "include": ["src/**/*"]
+}

package/verify.ts

@@ -0,0 +1,22 @@
+import { getBackend, BackendType } from './src';
+
+async function main() {
+  console.log('--- Neural 3.0 Verification ---');
+  
+  // Mock navigator for Node environment testing if needed, 
+  // but strictly this is meant for browser.
+  // We can just check if it compiles for now.
+  
+  try {
+    const backend = await getBackend(BackendType.Auto);
+    console.log(`Success: Initialized ${backend.name} backend.`);
+  } catch (err) {
+    if (typeof navigator === 'undefined') {
+        console.log('Running in Node - skipping browser-only initialization.');
+    } else {
+        console.error('Initialization failed:', err);
+    }
+  }
+}
+
+main();