wifi-densepose/crates/ruvector-learning-wasm/pkg/README.md

# @ruvector/learning-wasm - Ultra-Fast MicroLoRA for WebAssembly

[![npm version](https://img.shields.io/npm/v/ruvector-learning-wasm.svg)](https://www.npmjs.com/package/ruvector-learning-wasm)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://github.com/ruvnet/ruvector)
[![Bundle Size](https://img.shields.io/badge/bundle%20size-38KB%20gzip-green.svg)](https://www.npmjs.com/package/ruvector-learning-wasm)
[![WebAssembly](https://img.shields.io/badge/WebAssembly-654FF0?logo=webassembly&logoColor=white)](https://webassembly.org/)

Ultra-fast **Low-Rank Adaptation (LoRA)** for WebAssembly with sub-100 microsecond adaptation latency. Designed for real-time per-operator-type learning in query optimization systems, edge AI, and browser-based machine learning applications.

## Key Features

- **Rank-2 LoRA Architecture**: Minimal parameter count (2d parameters per adapter) for efficient edge deployment
- **Sub-100us Adaptation Latency**: Instant weight updates enabling real-time learning
- **Per-Operator Scoping**: Separate adapters for 17 different operator types (scan, filter, join, aggregate, etc.)
- **Zero-Allocation Forward Pass**: Direct memory access for maximum performance
- **Trajectory Buffer**: Track learning history with success rate analytics
- **WASM-Optimized**: no_std compatible with minimal allocations

## Installation

```bash
npm install ruvector-learning-wasm
# or
yarn add ruvector-learning-wasm
# or
pnpm add ruvector-learning-wasm
```

## Quick Start

### TypeScript/JavaScript

```typescript
import init, { WasmMicroLoRA, WasmScopedLoRA, WasmTrajectoryBuffer } from 'ruvector-learning-wasm';

// Initialize WASM module
await init();

// Create a MicroLoRA engine (256-dim embeddings)
const lora = new WasmMicroLoRA(256, 0.1, 0.01);

// Forward pass with typed arrays
const input = new Float32Array(256).fill(0.1);
const output = lora.forward_array(input);

// Adapt based on gradient
const gradient = new Float32Array(256);
gradient.fill(0.05);
lora.adapt_array(gradient);

// Or use reward-based adaptation
lora.adapt_with_reward(0.15); // 15% improvement

console.log(`Adaptations: ${lora.adapt_count()}`);
console.log(`Delta norm: ${lora.delta_norm()}`);
```

### Zero-Allocation Forward Pass

For maximum performance, use direct memory access:

```typescript
// Get buffer pointers
const inputPtr = lora.get_input_ptr();
const outputPtr = lora.get_output_ptr();

// Write directly to WASM memory
const memory = new Float32Array(wasmInstance.memory.buffer, inputPtr, 256);
memory.set(inputData);

// Execute forward pass (zero allocation)
lora.forward();

// Read output directly from WASM memory
const result = new Float32Array(wasmInstance.memory.buffer, outputPtr, 256);
```

### Per-Operator Scoped LoRA

```typescript
import { WasmScopedLoRA } from 'ruvector-learning-wasm';

const scopedLora = new WasmScopedLoRA(256, 0.1, 0.01);

// Operator types: 0=Scan, 1=Filter, 2=Join, 3=Aggregate, 4=Project, 5=Sort, ...
const SCAN_OP = 0;
const JOIN_OP = 2;

// Forward pass for specific operator
const scanOutput = scopedLora.forward_array(SCAN_OP, input);

// Adapt specific operator based on improvement
scopedLora.adapt_with_reward(JOIN_OP, 0.25);

// Get operator name
console.log(WasmScopedLoRA.scope_name(SCAN_OP)); // "Scan"

// Check per-operator statistics
console.log(`Scan adaptations: ${scopedLora.adapt_count(SCAN_OP)}`);
console.log(`Total adaptations: ${scopedLora.total_adapt_count()}`);
```

### Trajectory Tracking

```typescript
import { WasmTrajectoryBuffer } from 'ruvector-learning-wasm';

const buffer = new WasmTrajectoryBuffer(1000, 256);

// Record trajectories
buffer.record(
  embedding,      // Float32Array
  2,              // operator type (JOIN)
  5,              // attention mechanism used
  45.2,           // actual execution time (ms)
  120.5           // baseline execution time (ms)
);

// Analyze learning progress
console.log(`Success rate: ${(buffer.success_rate() * 100).toFixed(1)}%`);
console.log(`Best improvement: ${buffer.best_improvement()}x`);
console.log(`Mean improvement: ${buffer.mean_improvement()}x`);
console.log(`Best attention mechanism: ${buffer.best_attention()}`);

// Filter high-quality trajectories
const topTrajectories = buffer.high_quality_count(0.5); // >50% improvement
```

## Architecture

```
Input Embedding (d-dim)
       |
       v
  +---------+
  | A: d x 2 |  Down projection (d -> 2)
  +---------+
       |
       v
  +---------+
  | B: 2 x d |  Up projection (2 -> d)
  +---------+
       |
       v
Delta W = alpha * (A @ B)
       |
       v
Output = Input + Delta W
```

## Performance Benchmarks

| Operation | Latency | Throughput |
|-----------|---------|------------|
| Forward (256-dim) | ~15us | 66K ops/sec |
| Adapt (gradient) | ~25us | 40K ops/sec |
| Forward (zero-alloc) | ~8us | 125K ops/sec |
| Scoped forward | ~20us | 50K ops/sec |
| Trajectory record | ~5us | 200K ops/sec |

Tested on Chrome 120+ / Node.js 20+ with WASM SIMD support.

## API Reference

### WasmMicroLoRA

| Method | Description |
|--------|-------------|
| `new(dim?, alpha?, learning_rate?)` | Create engine (defaults: 256, 0.1, 0.01) |
| `forward_array(input)` | Forward pass with Float32Array |
| `forward()` | Zero-allocation forward using buffers |
| `adapt_array(gradient)` | Adapt with gradient vector |
| `adapt_with_reward(improvement)` | Reward-based adaptation |
| `delta_norm()` | Get weight change magnitude |
| `adapt_count()` | Number of adaptations |
| `reset()` | Reset to initial state |

### WasmScopedLoRA

| Method | Description |
|--------|-------------|
| `new(dim?, alpha?, learning_rate?)` | Create scoped manager |
| `forward_array(op_type, input)` | Forward for operator |
| `adapt_with_reward(op_type, improvement)` | Operator-specific adaptation |
| `scope_name(op_type)` | Get operator name (static) |
| `total_adapt_count()` | Total adaptations across all operators |
| `set_category_fallback(enabled)` | Enable category fallback |

### WasmTrajectoryBuffer

| Method | Description |
|--------|-------------|
| `new(capacity?, embedding_dim?)` | Create buffer |
| `record(embedding, op_type, attention_type, exec_ms, baseline_ms)` | Record trajectory |
| `success_rate()` | Get success rate (0.0-1.0) |
| `best_improvement()` | Get best improvement ratio |
| `mean_improvement()` | Get mean improvement ratio |
| `high_quality_count(threshold)` | Count trajectories above threshold |

## Use Cases

- **Query Optimization**: Learn optimal attention mechanisms per SQL operator
- **Edge AI Personalization**: Real-time model adaptation on user devices
- **Browser ML**: In-browser fine-tuning without server round-trips
- **Federated Learning**: Lightweight local adaptation for aggregation
- **Reinforcement Learning**: Fast policy adaptation from rewards

## Bundle Size

- **WASM binary**: ~39KB (uncompressed)
- **Gzip compressed**: ~15KB
- **JavaScript glue**: ~5KB

## Related Packages

- [ruvector-attention-unified-wasm](https://www.npmjs.com/package/ruvector-attention-unified-wasm) - 18+ attention mechanisms
- [ruvector-nervous-system-wasm](https://www.npmjs.com/package/ruvector-nervous-system-wasm) - Bio-inspired neural components
- [ruvector-economy-wasm](https://www.npmjs.com/package/ruvector-economy-wasm) - CRDT credit economy

## License

MIT OR Apache-2.0

## Links

- [GitHub Repository](https://github.com/ruvnet/ruvector)
- [Full Documentation](https://ruv.io)
- [Bug Reports](https://github.com/ruvnet/ruvector/issues)

---

**Keywords**: LoRA, Low-Rank Adaptation, machine learning, WASM, WebAssembly, neural network, edge AI, adaptation, fine-tuning, query optimization, real-time learning, micro LoRA, rank-2, browser ML