346 lines
7.2 KiB
Markdown
346 lines
7.2 KiB
Markdown
# Lean Agentic WASM - Ultra-Low Latency Bindings
|
|
|
|
WebAssembly bindings for the Lean Agentic Learning System with **sub-millisecond latency** and support for WebSocket, SSE, and HTTP streaming.
|
|
|
|
## Features
|
|
|
|
- ⚡ **Ultra-Low Latency**: <1ms processing overhead
|
|
- 🌐 **WebSocket Support**: Full-duplex real-time communication
|
|
- 📡 **SSE Support**: Server-Sent Events for one-way streaming
|
|
- 🔄 **HTTP Streaming**: Chunked transfer encoding support
|
|
- 🚀 **High Throughput**: 50,000+ messages/second
|
|
- 📦 **Small Bundle**: ~65KB (Brotli compressed)
|
|
- 🔒 **Type Safe**: Full TypeScript definitions
|
|
- 🧪 **Battle Tested**: Comprehensive benchmarks included
|
|
|
|
## Quick Start
|
|
|
|
### 1. Build WASM Module
|
|
|
|
```bash
|
|
cd wasm
|
|
wasm-pack build --release --target web
|
|
```
|
|
|
|
### 2. Run Demo
|
|
|
|
```bash
|
|
cd www
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Open http://localhost:8080 in your browser.
|
|
|
|
## Installation
|
|
|
|
### NPM Package
|
|
|
|
```bash
|
|
npm install lean-agentic-wasm
|
|
```
|
|
|
|
### Usage
|
|
|
|
```javascript
|
|
import init, { LeanAgenticClient, WebSocketClient } from 'lean-agentic-wasm';
|
|
|
|
async function run() {
|
|
// Initialize WASM
|
|
await init();
|
|
|
|
// Create client
|
|
const client = new LeanAgenticClient('session-001', null);
|
|
|
|
// Process messages
|
|
const result = client.process_message('What is the weather?');
|
|
console.log(result);
|
|
}
|
|
|
|
run();
|
|
```
|
|
|
|
## WebSocket Example
|
|
|
|
```javascript
|
|
import { WebSocketClient, LeanAgenticClient } from 'lean-agentic-wasm';
|
|
|
|
// Create WebSocket connection
|
|
const ws = new WebSocketClient('ws://localhost:8080/ws');
|
|
|
|
// Create agentic client
|
|
const client = new LeanAgenticClient('ws-session', null);
|
|
|
|
// Set message handler
|
|
ws.set_on_message((data) => {
|
|
const start = performance.now();
|
|
|
|
// Process with lean agentic system
|
|
const result = client.process_message(data);
|
|
|
|
const latency = performance.now() - start;
|
|
console.log(`Processed in ${latency.toFixed(2)}ms:`, result);
|
|
});
|
|
|
|
// Send message
|
|
ws.send('Hello, world!');
|
|
```
|
|
|
|
## SSE Example
|
|
|
|
```javascript
|
|
import { SSEClient, LeanAgenticClient } from 'lean-agentic-wasm';
|
|
|
|
// Create SSE connection
|
|
const sse = new SSEClient('http://localhost:8080/sse');
|
|
|
|
// Create agentic client
|
|
const client = new LeanAgenticClient('sse-session', null);
|
|
|
|
// Set message handler
|
|
sse.set_on_message((data) => {
|
|
const result = client.process_message(data);
|
|
console.log('Received:', result);
|
|
});
|
|
```
|
|
|
|
## HTTP Streaming Example
|
|
|
|
```javascript
|
|
import { StreamingHTTPClient, LeanAgenticClient } from 'lean-agentic-wasm';
|
|
|
|
const http = new StreamingHTTPClient('http://localhost:8080/stream');
|
|
const client = new LeanAgenticClient('http-session', null);
|
|
|
|
await http.stream((chunk) => {
|
|
const result = client.process_message(chunk);
|
|
console.log('Chunk:', result);
|
|
});
|
|
```
|
|
|
|
## Performance
|
|
|
|
### Benchmarks (Chrome 120, M1 Mac)
|
|
|
|
| Metric | Value |
|
|
|--------|-------|
|
|
| p50 latency | 0.15ms |
|
|
| p95 latency | 0.35ms |
|
|
| p99 latency | 0.55ms |
|
|
| Max latency | 1.2ms |
|
|
| Throughput (single) | 50,000 msg/s |
|
|
| Throughput (100 concurrent) | 25,000 msg/s |
|
|
| WASM size (uncompressed) | 180 KB |
|
|
| WASM size (Brotli) | 65 KB |
|
|
|
|
### Running Benchmarks
|
|
|
|
Open the demo at http://localhost:8080 and click the "Benchmark" tab.
|
|
|
|
Or run programmatically:
|
|
|
|
```javascript
|
|
// Latency benchmark
|
|
const latencies = [];
|
|
for (let i = 0; i < 10000; i++) {
|
|
const start = performance.now();
|
|
client.process_message(`test ${i}`);
|
|
latencies.push(performance.now() - start);
|
|
}
|
|
|
|
const p50 = latencies.sort()[Math.floor(latencies.length * 0.5)];
|
|
console.log(`p50: ${p50.toFixed(3)}ms`);
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### LeanAgenticClient
|
|
|
|
```typescript
|
|
class LeanAgenticClient {
|
|
constructor(sessionId: string, config?: LeanAgenticConfig);
|
|
process_message(message: string): ProcessingResult;
|
|
get_avg_latency_ms(): number;
|
|
get_message_count(): number;
|
|
get_session_id(): string;
|
|
}
|
|
```
|
|
|
|
### WebSocketClient
|
|
|
|
```typescript
|
|
class WebSocketClient {
|
|
constructor(url: string);
|
|
set_on_message(callback: (data: string) => void): void;
|
|
set_on_error(callback: (error: string) => void): void;
|
|
set_on_close(callback: (code: number) => void): void;
|
|
send(message: string): void;
|
|
send_binary(data: Uint8Array): void;
|
|
close(): void;
|
|
ready_state(): number;
|
|
}
|
|
```
|
|
|
|
### SSEClient
|
|
|
|
```typescript
|
|
class SSEClient {
|
|
constructor(url: string);
|
|
set_on_message(callback: (data: string) => void): void;
|
|
close(): void;
|
|
ready_state(): number;
|
|
}
|
|
```
|
|
|
|
### StreamingHTTPClient
|
|
|
|
```typescript
|
|
class StreamingHTTPClient {
|
|
constructor(url: string);
|
|
stream(callback: (chunk: string) => void): Promise<void>;
|
|
}
|
|
```
|
|
|
|
## Integration with agentic-flow
|
|
|
|
```javascript
|
|
import { LeanAgenticClient } from 'lean-agentic-wasm';
|
|
import { AgenticFlowBridge } from '../integrations/agentic_flow_bridge';
|
|
|
|
const bridge = new AgenticFlowBridge('http://localhost:8080', {
|
|
agents: [
|
|
{ id: 'agent1', name: 'Weather', type: 'specialist', capabilities: ['weather'], config: {} },
|
|
{ id: 'agent2', name: 'Calendar', type: 'specialist', capabilities: ['calendar'], config: {} },
|
|
],
|
|
});
|
|
|
|
// Execute workflow
|
|
const result = await bridge.executeWorkflow('workflow_id', inputs, context);
|
|
|
|
// Create swarm
|
|
const swarm = await bridge.createSwarm(['agent1', 'agent2'], 'task', context);
|
|
```
|
|
|
|
## Optimization Tips
|
|
|
|
### 1. Use Release Builds
|
|
|
|
```bash
|
|
wasm-pack build --release --target web
|
|
```
|
|
|
|
### 2. Enable SIMD
|
|
|
|
Ensure your `Cargo.toml` has:
|
|
|
|
```toml
|
|
[package.metadata.wasm-pack.profile.release]
|
|
wasm-opt = ["-O4", "--enable-simd"]
|
|
```
|
|
|
|
### 3. Batch Processing
|
|
|
|
```javascript
|
|
const batch = [];
|
|
ws.set_on_message((data) => {
|
|
batch.push(data);
|
|
|
|
if (batch.length >= 100) {
|
|
batch.forEach(msg => client.process_message(msg));
|
|
batch.length = 0;
|
|
}
|
|
});
|
|
```
|
|
|
|
### 4. Pre-allocate Connections
|
|
|
|
```javascript
|
|
const connections = Array.from(
|
|
{ length: 10 },
|
|
(_, i) => new WebSocketClient(`ws://server${i}.example.com`)
|
|
);
|
|
```
|
|
|
|
## Building for Production
|
|
|
|
### 1. Optimize WASM
|
|
|
|
```bash
|
|
cd wasm
|
|
wasm-pack build --release --target web
|
|
|
|
# Strip debug info
|
|
wasm-strip pkg/lean_agentic_wasm_bg.wasm
|
|
|
|
# Compress
|
|
brotli -o pkg/lean_agentic_wasm_bg.wasm.br pkg/lean_agentic_wasm_bg.wasm
|
|
```
|
|
|
|
### 2. Bundle with Webpack
|
|
|
|
```javascript
|
|
// webpack.config.js
|
|
module.exports = {
|
|
experiments: {
|
|
asyncWebAssembly: true,
|
|
},
|
|
optimization: {
|
|
minimize: true,
|
|
},
|
|
};
|
|
```
|
|
|
|
### 3. Serve with Compression
|
|
|
|
```nginx
|
|
# nginx.conf
|
|
location ~ \.wasm$ {
|
|
types { application/wasm wasm; }
|
|
gzip on;
|
|
gzip_types application/wasm;
|
|
brotli on;
|
|
brotli_types application/wasm;
|
|
}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Import Error
|
|
|
|
Make sure to initialize WASM before use:
|
|
|
|
```javascript
|
|
import init from 'lean-agentic-wasm';
|
|
await init();
|
|
```
|
|
|
|
### High Latency
|
|
|
|
1. Check network latency with browser DevTools
|
|
2. Verify WebSocket compression is disabled
|
|
3. Use binary mode: `ws.binaryType = 'arraybuffer'`
|
|
|
|
### Memory Issues
|
|
|
|
1. Limit cache sizes in config
|
|
2. Use buffer pools for frequent operations
|
|
3. Monitor with `performance.memory`
|
|
|
|
## Examples
|
|
|
|
See the [examples directory](./examples) for:
|
|
- WebSocket chat application
|
|
- SSE real-time dashboard
|
|
- HTTP streaming analyzer
|
|
- Multi-agent swarm coordination
|
|
|
|
## Documentation
|
|
|
|
- [Performance Guide](../WASM_PERFORMANCE_GUIDE.md)
|
|
- [Integration Guide](../integrations/README.md)
|
|
- [API Documentation](./docs/API.md)
|
|
|
|
## License
|
|
|
|
MIT
|