npm package: @ruvector/edge
Description: Free edge-based AI swarms in the browser - P2P, crypto, vector search, neural networks. Install @ruvector/edge-full for graph DB, SQL, ONNX embeddings.
Author: RuVector Team
Latest version: 0.1.9

# @ruvector/edge

[![npm](https://img.shields.io/npm/v/@ruvector/edge.svg)](https://www.npmjs.com/package/@ruvector/edge)
[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![WASM](https://img.shields.io/badge/wasm-364KB-purple.svg)]()
[![Tests](https://img.shields.io/badge/tests-60%20passing-brightgreen.svg)]()

## Free Self-Learning AI Swarms at the Edge

**Build and deploy self-optimizing AI agent swarms that run entirely in web browsers, mobile devices, and edge servers - without paying for cloud infrastructure.**

Imagine having dozens of AI agents working together - analyzing data, routing tasks, making decisions, and getting smarter with every interaction - all running directly in your users' browsers. No API costs. No server bills. No data leaving your network. That's what @ruvector/edge makes possible.

This library gives you everything you need to build distributed AI systems: cryptographic identity for each agent, encrypted communication between them, lightning-fast vector search for finding the right agent for each task, consensus protocols so your agents can coordinate without a central server, and self-learning neural networks that continuously optimize agent routing based on real-world outcomes. It's all compiled to a tiny 364KB WebAssembly binary that runs anywhere JavaScript runs.

**The key insight:** Instead of paying cloud providers to run your AI infrastructure, you use the computing power that's already there - your users' devices. Each browser becomes a node in your swarm. The more users you have, the more powerful your system becomes - and with built-in self-learning capabilities (LoRA fine-tuning, EWC++ continual learning, ReasoningBank experience replay), your swarm gets smarter over time while still costing you nothing.

```
┌─────────────────────────────────────────────────────────────────────┐
│                         ZERO COST SWARMS                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐   │
│   │ Browser │◄────►│ Browser │◄────►│  Edge   │◄────►│  Mobile │   │
│   │ Agent A │      │ Agent B │      │ Agent C │      │ Agent D │   │
│   └─────────┘      └─────────┘      └─────────┘      └─────────┘   │
│        │                │                │                │        │
│        └────────────────┴────────────────┴────────────────┘        │
│                              P2P Mesh                               │
│                                                                     │
│   Compute: FREE (runs on user devices)                              │
│   Network: FREE (public relays + P2P)                               │
│   Storage: FREE (distributed across nodes)                          │
│   Scale:   UNLIMITED (each user = new node)                         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### What You Get

| Capability | Technology | Performance |
|------------|------------|-------------|
| **Agent Identity** | Ed25519 signatures | 50,000 ops/sec |
| **Encryption** | AES-256-GCM | 1 GB/sec |
| **Vector Search** | HNSW index | 150x faster than brute force |
| **Task Routing** | Semantic LSH | Sub-millisecond |
| **Trusted Consensus** | Raft protocol | For stable cohorts (teams, rooms) |
| **Open Swarm** | Gossip + CRDT | High-churn, Byzantine-tolerant |
| **Post-Quantum** | Hybrid signatures | Future-proof |
| **Neural Networks** | Spiking + STDP | Bio-inspired learning |
| **Compression** | Adaptive 4-32x | Network-aware |
| **Web Workers** | Worker pool | Parallel ops, non-blocking UI |

### What It Costs

| Component | Cloud Solution | @ruvector/edge |
|-----------|---------------|----------------|
| Compute | $200-500/month | **$0** (user's CPU) |
| Vector DB | $100-300/month | **$0** (in-browser HNSW) |
| Encryption | $50-100/month | **$0** (built-in AES) |
| Bandwidth | $0.09/GB | **$0** (P2P direct) |
| Consensus | $100-200/month | **$0** (built-in Raft) |
| **Total** | **$450-1100/month** | **$0/month** |

---

## Full Platform Capabilities

RuVector provides a complete edge AI platform. This package (`@ruvector/edge`) is the lightweight core. For the full toolkit, install `@ruvector/edge-full`.

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        RUVECTOR EDGE PLATFORM                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  @ruvector/edge (364KB)              @ruvector/edge-full (+8MB)             │
│  ─────────────────────               ───────────────────────────            │
│  ✓ Ed25519 Identity                  Everything in edge, PLUS:              │
│  ✓ AES-256-GCM Encryption                                                   │
│  ✓ HNSW Vector Search                ✓ Graph DB (288KB)                     │
│  ✓ Semantic Task Routing               Neo4j-style API, Cypher queries      │
│  ✓ Raft (trusted cohorts)              Relationship modeling, traversals    │
│  ✓ Gossip + CRDT (open swarms)                                              │
│  ✓ Post-Quantum Crypto               ✓ RVLite Vector DB (260KB)             │
│  ✓ Spiking Neural Networks             SQL + SPARQL + Cypher queries        │
│  ✓ Adaptive Compression                IndexedDB persistence                │
│  ✓ Web Worker Pool                                                          │
│                                                                             │
│  Best for:                           ✓ SONA Neural Router (238KB)           │
│  • Lightweight P2P apps                Self-learning with LoRA              │
│  • Secure messaging                    EWC++ continual learning             │
│  • Trusted team swarms                 ReasoningBank experience replay      │
│  • Mobile/embedded                                                          │
│                                                                             │
│                                      ✓ DAG Workflows (132KB)                │
│                                        Task orchestration                   │
│                                        Dependency resolution                │
│                                        Topological execution                │
│                                                                             │
│                                      ✓ ONNX Embeddings (7.1MB)              │
│                                        6 HuggingFace models                 │
│                                        3.8x parallel speedup                │
│                                        MiniLM, BGE, E5, GTE                 │
│                                                                             │
│                                      Best for:                              │
│                                      • Full RAG pipelines                   │
│                                      • Knowledge graphs                     │
│                                      • Self-learning agents                 │
│                                      • Complex workflows                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Choose Your Package

```bash
# Lightweight core (364KB) - P2P, crypto, vectors, consensus
npm install @ruvector/edge

# Full platform (8.4MB) - adds graph DB, SQL, neural routing, ONNX
npm install @ruvector/edge-full
```

### Using Both Together

```javascript
// Start with edge core
import init, { WasmIdentity, WasmHnswIndex } from '@ruvector/edge';

// Add full capabilities when needed
import { graph, rvlite, sona, dag } from '@ruvector/edge-full';
import onnxInit from '@ruvector/edge-full/onnx';
```

---

### Consensus Modes: Trusted vs Open

RuVector provides two coordination strategies for different deployment scenarios:

| Mode | Protocol | When to Use |
|------|----------|-------------|
| **Trusted Cohort** | Raft | Private teams, enterprise LANs, known membership, low churn |
| **Open Swarm** | Gossip + CRDT | Public networks, anonymous browsers, high churn, adversarial environments |

```javascript
// Trusted cohort (Raft) - stable team of 3-7 nodes
const raftNode = new WasmRaftNode('node-1', ['node-1', 'node-2', 'node-3']);
raftNode.start_election();  // Leader election for consistent state

// Open swarm (Gossip + CRDT) - dynamic browser mesh
const gossipNode = new WasmGossipNode(identity);
gossipNode.join_swarm(relayUrl);  // Eventually consistent, Byzantine-tolerant
```

**Why two modes?** Raft assumes known membership and trusted nodes - perfect for your dev team or enterprise deployment. But a public browser swarm has nodes joining/leaving constantly and can't trust everyone. Gossip protocols with CRDTs handle this gracefully: no leader election, no membership tracking, eventual consistency that converges even with malicious actors.

---

### Web Workers: Keep the UI Responsive

Heavy operations (vector search, encryption, neural network inference) run in Web Workers to avoid blocking the main thread. The package includes a ready-to-use worker pool:

```javascript
import { WorkerPool } from '@ruvector/edge/worker-pool';

// Create worker pool (auto-detects CPU cores)
const pool = new WorkerPool(
  new URL('@ruvector/edge/worker', import.meta.url),
  new URL('@ruvector/edge/ruvector_edge_bg.wasm', import.meta.url),
  {
    poolSize: navigator.hardwareConcurrency,
    dimensions: 384,
    useHnsw: true
  }
);

await pool.init();

// Operations run in parallel across workers
await pool.insert(embedding, 'doc-1', { title: 'Hello' });
await pool.insertBatch([
  { vector: emb1, id: 'doc-2' },
  { vector: emb2, id: 'doc-3' },
  { vector: emb3, id: 'doc-4' }
]);

// Search distributed across workers
const results = await pool.search(queryEmbedding, 10);

// Batch search (each query on different worker)
const batchResults = await pool.searchBatch([query1, query2, query3], 10);

// Pool statistics
console.log(pool.getStats());
// { poolSize: 8, busyWorkers: 2, idleWorkers: 6, pendingRequests: 0 }

// Clean up
pool.terminate();
```

**Worker Pool Features:**
- Round-robin task distribution with load balancing
- Automatic batch splitting across workers
- Promise-based API with 30s timeout
- Zero-copy transfers via transferable objects
- Works in browsers, Deno, and Cloudflare Workers

---

### Quick Start

```bash
npm install @ruvector/edge
```

```javascript
import init, { WasmIdentity, WasmHnswIndex, WasmSemanticMatcher } from '@ruvector/edge';

await init();

// Create agent identity
const identity = WasmIdentity.generate();
console.log(`Agent: ${identity.agent_id()}`);

// Vector search (150x faster)
const index = new WasmHnswIndex(128, 16, 200);
index.insert("agent-1", new Float32Array(128));

// Semantic task routing
const matcher = new WasmSemanticMatcher();
matcher.register_agent("coder", "rust typescript javascript");
const best = matcher.find_best_agent("write a function");
```

---

## Table of Contents

1. [Why Edge-First?](#why-edge-first)
2. [Features](#features)
3. [Tutorial: Build Your First Swarm](#tutorial-build-your-first-swarm)
4. [P2P Transport Options](#p2p-transport-options)
5. [Free Infrastructure](#free-infrastructure-zero-cost-at-any-scale)
6. [Architecture](#architecture)
7. [API Reference](#api-reference)
8. [Performance](#performance)
9. [Security](#security)

---

## Why Edge-First?

| Traditional Cloud Swarms | RuVector Edge Swarms |
|--------------------------|---------------------|
| Pay per API call | **Free forever** |
| Data leaves your network | **Data stays local** |
| Central point of failure | **Fully distributed** |
| Vendor lock-in | **Open source** |
| High latency (round-trip to cloud) | **Sub-millisecond (peer-to-peer)** |
| Limited by server capacity | **Scales with your devices** |

### The Economics of Edge AI

```
Cloud AI Swarm (10 agents, 1M operations/month):
├── API calls:        $500-2000/month
├── Compute:          $200-500/month
├── Bandwidth:        $50-100/month
└── Total:            $750-2600/month

RuVector Edge Swarm:
├── Infrastructure:   $0
├── API calls:        $0
├── Bandwidth:        $0 (P2P)
└── Total:            $0/month forever
```

### How Is It Free?

The code runs on devices you already own - there's no server to pay for:

```
Traditional Architecture:
┌──────────┐     ┌─────────────────┐     ┌──────────┐
│ Agent A  │────►│  Cloud Server   │◄────│ Agent B  │
└──────────┘     │  ($$$$/month)   │     └──────────┘
                 └─────────────────┘

Edge Architecture:
┌──────────┐◄───────────────────────────►┌──────────┐
│ Agent A  │         Direct P2P          │ Agent B  │
│ (Browser)│         Connection          │ (Browser)│
└──────────┘                             └──────────┘
                 No server = No cost
```

---

## Features

| Feature | Description |
|---------|-------------|
| **Ed25519 Identity** | Cryptographic agent identity with signing |
| **AES-256-GCM** | Authenticated encryption for all messages |
| **Post-Quantum Hybrid** | Future-proof against quantum attacks |
| **HNSW Vector Index** | 150x faster similarity search |
| **Semantic Matching** | Intelligent task-to-agent routing |
| **Raft Consensus** | Distributed leader election |
| **Spiking Networks** | Bio-inspired temporal learning |
| **Adaptive Compression** | Network-aware bandwidth optimization |

---

## Quick Start

### Installation

```bash
npm install @ruvector/edge
```

### Basic Usage

```javascript
import init, {
  WasmIdentity,
  WasmCrypto,
  WasmHnswIndex,
  WasmSemanticMatcher
} from '@ruvector/edge';

// Initialize WASM (required once)
await init();

// Create an agent
const agent = WasmIdentity.generate();
console.log(`Agent: ${agent.agent_id()}`);

// Encrypt a message
const crypto = new WasmCrypto();
const key = crypto.generate_key();
const encrypted = crypto.encrypt(key, new TextEncoder().encode("Hello swarm!"));

// Search vectors
const index = new WasmHnswIndex(128, 16, 200);
index.insert("doc-1", new Float32Array(128).fill(0.5));
const results = index.search(new Float32Array(128).fill(0.5), 5);

// Route tasks
const matcher = new WasmSemanticMatcher();
matcher.register_agent("coder", "rust typescript javascript");
const best = matcher.find_best_agent("write a function");
```

---

## Tutorial: Build Your First Swarm

This tutorial walks you through building a complete AI agent swarm that runs entirely in browsers with no backend.

### Prerequisites

```bash
mkdir my-swarm && cd my-swarm
npm init -y
npm install @ruvector/edge
```

Create `index.html`:

```html
<!DOCTYPE html>
<html>
<head><title>My AI Swarm</title></head>
<body>
  <div id="status"></div>
  <script type="module" src="swarm.js"></script>
</body>
</html>
```

---

### Step 1: Agent Identity

Every agent needs a unique cryptographic identity. This enables signing messages and verifying authenticity.

Create `swarm.js`:

```javascript
import init, { WasmIdentity } from '@ruvector/edge';

async function createAgent(name) {
  await init();

  // Generate Ed25519 keypair
  const identity = WasmIdentity.generate();

  console.log(`Agent: ${name}`);
  console.log(`  ID: ${identity.agent_id()}`);
  console.log(`  Public Key: ${identity.public_key_hex().slice(0, 16)}...`);

  return identity;
}

// Create our agent
const myAgent = await createAgent("Worker-001");

// Sign a message to prove identity
const message = new TextEncoder().encode("I am Worker-001");
const signature = myAgent.sign(message);
console.log(`  Signature: ${signature.slice(0, 8).join(',')}...`);

// Verify the signature
const isValid = myAgent.verify(message, signature);
console.log(`  Valid: ${isValid}`); // true
```

**What's happening:**
- `WasmIdentity.generate()` creates an Ed25519 keypair
- `agent_id()` returns a unique identifier derived from the public key
- `sign()` creates a cryptographic signature proving the message came from this agent
- `verify()` checks if a signature is valid

---

### Step 2: Secure Communication

Agents need to encrypt messages so only intended recipients can read them.

```javascript
import init, { WasmIdentity, WasmCrypto } from '@ruvector/edge';

await init();

const crypto = new WasmCrypto();

// Agent A wants to send a secret message to Agent B
const agentA = WasmIdentity.generate();
const agentB = WasmIdentity.generate();

// Generate a shared secret key (in real app, use key exchange)
const sharedKey = crypto.generate_key();

// Agent A encrypts
const plaintext = new TextEncoder().encode(JSON.stringify({
  task: "analyze_data",
  payload: { dataset: "sales_2024.csv" }
}));

const ciphertext = crypto.encrypt(sharedKey, plaintext);
console.log(`Encrypted: ${ciphertext.length} bytes`);

// Agent B decrypts
const decrypted = crypto.decrypt(sharedKey, ciphertext);
const message = JSON.parse(new TextDecoder().decode(decrypted));
console.log(`Decrypted: ${message.task}`); // "analyze_data"
```

**Security features:**
- AES-256-GCM authenticated encryption
- Random nonce per message (replay protection)
- Ciphertext integrity verification

---

### Step 3: Vector Search

Agents need to find each other based on capabilities. HNSW enables fast similarity search.

```javascript
import init, { WasmHnswIndex } from '@ruvector/edge';

await init();

// Create index: 128 dimensions, M=16 connections, ef=200 search quality
const index = new WasmHnswIndex(128, 16, 200);

// Register agents with their capability embeddings
// (In production, use real embeddings from a model)
function mockEmbedding(weights) {
  const vec = new Float32Array(128);
  weights.forEach((w, i) => vec[i] = w);
  return vec;
}

// Register specialized agents
index.insert("rust-expert", mockEmbedding([0.9, 0.1, 0.0, 0.0]));
index.insert("python-expert", mockEmbedding([0.1, 0.9, 0.0, 0.0]));
index.insert("ml-expert", mockEmbedding([0.0, 0.5, 0.9, 0.0]));
index.insert("devops-expert", mockEmbedding([0.0, 0.0, 0.2, 0.9]));

console.log(`Index size: ${index.len()} agents`);

// Find best agent for a Rust task
const rustTask = mockEmbedding([0.85, 0.1, 0.05, 0.0]);
const results = index.search(rustTask, 3);

console.log("Best agents for Rust task:");
results.forEach(([id, distance]) => {
  console.log(`  ${id}: distance=${distance.toFixed(3)}`);
});
// Output: rust-expert: distance=0.050
```

**Why HNSW?**
- O(log n) search instead of O(n)
- 150x faster than brute force at 10K+ vectors
- Memory-efficient graph structure

---

### Step 4: Task Routing

Route tasks to the best agent using semantic matching.

```javascript
import init, { WasmSemanticMatcher } from '@ruvector/edge';

await init();

const matcher = new WasmSemanticMatcher();

// Register agents with capability descriptions
matcher.register_agent("code-agent",
  "rust typescript javascript python programming coding functions classes");
matcher.register_agent("data-agent",
  "python pandas numpy data analysis statistics csv excel");
matcher.register_agent("devops-agent",
  "docker kubernetes terraform aws deploy infrastructure cicd");
matcher.register_agent("writing-agent",
  "documentation markdown readme technical writing blog");

console.log(`Registered ${matcher.agent_count()} agents`);

// Route tasks to best agent
const tasks = [
  "Write a Rust function to parse JSON",
  "Analyze the sales data in this CSV",
  "Deploy the app to Kubernetes",
  "Update the API documentation"
];

tasks.forEach(task => {
  const best = matcher.find_best_agent(task);
  console.log(`"${task.slice(0, 30)}..." → ${best}`);
});

// Output:
// "Write a Rust function..." → code-agent
// "Analyze the sales data..." → data-agent
// "Deploy the app to Kube..." → devops-agent
// "Update the API documen..." → writing-agent
```

**How it works:**
- LSH (Locality-Sensitive Hashing) creates semantic fingerprints
- Tasks are matched to agents by fingerprint similarity
- Sub-millisecond routing even with many agents

---

### Step 5: Distributed Consensus

When multiple agents need to agree on a leader or shared state, use Raft consensus.

```javascript
import init, { WasmRaftNode } from '@ruvector/edge';

await init();

// Create a 3-node cluster
const members = ["node-1", "node-2", "node-3"];

const node1 = new WasmRaftNode("node-1", members);
const node2 = new WasmRaftNode("node-2", members);
const node3 = new WasmRaftNode("node-3", members);

console.log(`Node 1 state: ${node1.state()}`); // "follower"
console.log(`Node 1 term: ${node1.current_term()}`); // 0

// Node 1 times out and starts election
const voteRequest = node1.start_election();
console.log(`Node 1 state: ${node1.state()}`); // "candidate"
console.log(`Node 1 term: ${node1.current_term()}`); // 1

// Simulate: Node 2 and 3 grant votes
// (In real app, send voteRequest over network, receive responses)
const granted1 = node1.receive_vote(true);
const granted2 = node1.receive_vote(true);

console.log(`Node 1 state: ${node1.state()}`); // "leader"

// Leader can now coordinate the swarm!
console.log("Leader elected - swarm can coordinate");
```

**Raft guarantees:**
- Only one leader at a time
- Leader election in 1-2 round trips
- Tolerates f failures in 2f+1 nodes

---

## P2P Transport Options

RuVector Edge provides the intelligence layer. You need a transport layer for agents to communicate. Here are your free options:

### Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                    @ruvector/edge (WASM)                    │
│  Identity, Crypto, HNSW, Semantic Matching, Raft, etc.      │
└─────────────────────────────────────────────────────────────┘
                              │
                    Transport Layer (choose one)
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
   ┌─────────┐          ┌─────────┐          ┌─────────┐
   │ WebRTC  │          │  GUN.js │          │  IPFS/  │
   │  (P2P)  │          │  (P2P)  │          │ libp2p  │
   └─────────┘          └─────────┘          └─────────┘
```

---

### Option 1: WebRTC (Browser-to-Browser)

**Best for:** Direct browser-to-browser communication
**Cost:** Free (need minimal signaling server)

```javascript
import init, { WasmIdentity, WasmCrypto } from '@ruvector/edge';

await init();

const identity = WasmIdentity.generate();
const crypto = new WasmCrypto();

// Create peer connection
const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] // Free STUN
});

// Create data channel for agent messages
const channel = pc.createDataChannel('swarm');

channel.onopen = () => {
  console.log('P2P connection established!');

  // Send encrypted message
  const key = crypto.generate_key(); // Exchange via signaling
  const message = { type: 'task', data: 'analyze this' };
  const encrypted = crypto.encrypt(key,
    new TextEncoder().encode(JSON.stringify(message))
  );

  channel.send(encrypted);
};

channel.onmessage = (event) => {
  const decrypted = crypto.decrypt(key, new Uint8Array(event.data));
  const message = JSON.parse(new TextDecoder().decode(decrypted));
  console.log('Received:', message);
};

// Signaling (exchange offer/answer via any method)
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
// Send offer to peer via signaling server, WebSocket, or even QR code
```

**Free signaling options:**
- PeerJS Cloud (free tier)
- Firebase Realtime Database (free tier)
- Your own WebSocket on Fly.io/Railway free tier

---

### Option 2: GUN.js (Decentralized Database)

**Best for:** Real-time sync, offline-first, no server needed
**Cost:** Completely free (public relay network)

```javascript
import init, { WasmIdentity, WasmSemanticMatcher } from '@ruvector/edge';
import Gun from 'gun';

await init();

const identity = WasmIdentity.generate();
const matcher = new WasmSemanticMatcher();

// Connect to public GUN relays (free!)
const gun = Gun(['https://gun-manhattan.herokuapp.com/gun']);

// Create swarm namespace
const swarm = gun.get('my-ai-swarm');

// Register this agent
swarm.get('agents').get(identity.agent_id()).put({
  id: identity.agent_id(),
  capabilities: 'rust typescript programming',
  publicKey: identity.public_key_hex(),
  online: true,
  timestamp: Date.now()
});

// Listen for new agents
swarm.get('agents').map().on((agent, id) => {
  if (agent && agent.id !== identity.agent_id()) {
    console.log(`Discovered agent: ${agent.id}`);
    matcher.register_agent(agent.id, agent.capabilities);
  }
});

// Publish tasks
swarm.get('tasks').set({
  id: crypto.randomUUID(),
  description: 'Write a Rust function',
  from: identity.agent_id(),
  timestamp: Date.now()
});

// Listen for tasks
swarm.get('tasks').map().on((task) => {
  if (task) {
    const bestAgent = matcher.find_best_agent(task.description);
    if (bestAgent === identity.agent_id()) {
      console.log(`I should handle: ${task.description}`);
    }
  }
});
```

**Why GUN?**
- No server required - uses public relays
- Offline-first with automatic sync
- Real-time updates via WebSocket
- Already integrated in RuVector Edge (Rust side)

---

### Option 3: IPFS + libp2p

**Best for:** Content-addressed storage + P2P messaging
**Cost:** Free (self-host) or free tier (Pinata, Infura)

```javascript
import init, { WasmIdentity, WasmCrypto } from '@ruvector/edge';
import { createLibp2p } from 'libp2p';
import { webSockets } from '@libp2p/websockets';
import { noise } from '@chainsafe/libp2p-noise';
import { gossipsub } from '@chainsafe/libp2p-gossipsub';

await init();

const identity = WasmIdentity.generate();
const crypto = new WasmCrypto();

// Create libp2p node
const node = await createLibp2p({
  transports: [webSockets()],
  connectionEncryption: [noise()],
  pubsub: gossipsub()
});

await node.start();

// Subscribe to swarm topic
const topic = 'my-ai-swarm';

node.pubsub.subscribe(topic);
node.pubsub.addEventListener('message', (event) => {
  if (event.detail.topic === topic) {
    const message = JSON.parse(new TextDecoder().decode(event.detail.data));
    console.log('Received:', message);
  }
});

// Publish to swarm
node.pubsub.publish(topic, new TextEncoder().encode(JSON.stringify({
  from: identity.agent_id(),
  type: 'announce',
  capabilities: ['rust', 'wasm']
})));
```

**IPFS for artifacts:**

```javascript
import { create } from 'ipfs-http-client';

// Use free Infura IPFS gateway
const ipfs = create({ url: 'https://ipfs.infura.io:5001' });

// Store agent output
const result = await ipfs.add(JSON.stringify({
  task: 'analyze-data',
  output: { summary: '...' },
  agent: identity.agent_id(),
  signature: identity.sign(...)
}));

console.log(`Stored at: ipfs://${result.cid}`);

// Share CID with swarm - anyone can fetch
```

---

### Option 4: Nostr Relays

**Best for:** Simple pub/sub with free public infrastructure
**Cost:** Free (many public relays)

```javascript
import init, { WasmIdentity } from '@ruvector/edge';
import { relayInit, getEventHash, signEvent } from 'nostr-tools';

await init();

const identity = WasmIdentity.generate();

// Connect to free public relay
const relay = relayInit('wss://relay.damus.io');
await relay.connect();

// Create Nostr event (signed message)
const event = {
  kind: 29000, // Custom kind for AI swarm
  created_at: Math.floor(Date.now() / 1000),
  tags: [['swarm', 'my-ai-swarm']],
  content: JSON.stringify({
    agentId: identity.agent_id(),
    type: 'task',
    data: 'Write a function'
  })
};

// Sign with identity (Nostr uses secp256k1, so bridge needed)
// Or use Nostr's native keys alongside RuVector identity

// Subscribe to swarm events
const sub = relay.sub([
  { kinds: [29000], '#swarm': ['my-ai-swarm'] }
]);

sub.on('event', (event) => {
  const message = JSON.parse(event.content);
  console.log(`From ${message.agentId}: ${message.type}`);
});
```

---

### Transport Comparison

| Transport | Latency | Offline | Complexity | Best For |
|-----------|---------|---------|------------|----------|
| **WebRTC** | ~50ms | No | Medium | Real-time, gaming |
| **GUN.js** | ~100ms | Yes | Low | General purpose |
| **IPFS/libp2p** | ~200ms | Partial | High | Content storage |
| **Nostr** | ~150ms | No | Low | Simple messaging |

### Recommended: Start with GUN.js

```bash
npm install gun @ruvector/edge
```

GUN requires zero setup, works offline, and has a free public relay network.

---

## Free Infrastructure (Zero Cost at Any Scale)

The entire stack can run for **$0/month** using public infrastructure:

### Free GUN Relays (Unlimited)

```javascript
const gun = Gun([
  'https://gun-manhattan.herokuapp.com/gun',
  'https://gun-us.herokuapp.com/gun',
  'https://gunjs.herokuapp.com/gun',
  'https://gun-eu.herokuapp.com/gun'
]);
// No signup, no limits, community-run
```

### Free STUN Servers (WebRTC)

```javascript
const rtcConfig = {
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },      // Google
    { urls: 'stun:stun1.l.google.com:19302' },     // Google
    { urls: 'stun:stun.cloudflare.com:3478' },     // Cloudflare
    { urls: 'stun:stun.services.mozilla.com' },    // Mozilla
    { urls: 'stun:stun.stunprotocol.org:3478' }    // Open source
  ]
};
// Unlimited, no account needed
```

### Free TURN Servers (NAT Traversal)

| Provider | Free Tier | Signup |
|----------|-----------|--------|
| **Metered.ca** | 500MB/month | Yes |
| **Xirsys** | 500MB/month | Yes |
| **Twilio** | $15 free credit | Yes |
| **OpenRelay** | Unlimited | No |

### Free Signaling Services

| Service | Free Tier | Best For |
|---------|-----------|----------|
| **PeerJS Cloud** | Unlimited connections | WebRTC signaling |
| **Firebase Realtime** | 1GB storage, 10GB/month | Real-time sync |
| **Supabase Realtime** | 500MB, unlimited connections | PostgreSQL + realtime |
| **Ably** | 6M messages/month | Pub/sub |
| **Pusher** | 200K messages/day | Simple messaging |

### Free Nostr Relays (Unlimited)

```javascript
const NOSTR_RELAYS = [
  'wss://relay.damus.io',
  'wss://nos.lol',
  'wss://relay.nostr.band',
  'wss://nostr.wine',
  'wss://relay.snort.social'
];
// No signup, no limits, decentralized
```

### Free Self-Hosting

| Platform | Free Tier | Use Case |
|----------|-----------|----------|
| **Fly.io** | 3 shared VMs, 160GB transfer | GUN/WebSocket relay |
| **Railway** | $5 credit/month | Any relay |
| **Render** | 750 hours/month | Static + WebSocket |
| **Cloudflare Workers** | 100K requests/day | Edge signaling |
| **Deno Deploy** | 1M requests/month | Edge relay |
| **Vercel Edge** | 1M invocations/month | Signaling |

### Complete Free Stack Example

```javascript
import init, { WasmIdentity, WasmSemanticMatcher } from '@ruvector/edge';
import Gun from 'gun';

await init();

// 1. Free GUN relays (unlimited scale)
const gun = Gun(['https://gun-manhattan.herokuapp.com/gun']);

// 2. Free WebRTC STUN (unlimited)
const rtcConfig = {
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },
    { urls: 'stun:stun.cloudflare.com:3478' }
  ]
};

// 3. Your swarm - $0/month forever
const identity = WasmIdentity.generate();
const matcher = new WasmSemanticMatcher();
const swarm = gun.get('my-ai-swarm');

// Register agent
swarm.get('agents').get(identity.agent_id()).put({
  id: identity.agent_id(),
  capabilities: 'coding analysis research',
  publicKey: identity.public_key_hex(),
  online: true
});

// Discover other agents
swarm.get('agents').map().on((agent, id) => {
  if (agent && agent.id !== identity.agent_id()) {
    matcher.register_agent(agent.id, agent.capabilities);
    console.log(`Discovered: ${agent.id}`);
  }
});

// Route and execute tasks
swarm.get('tasks').map().on((task) => {
  if (task) {
    const best = matcher.find_best_agent(task.description);
    if (best === identity.agent_id()) {
      console.log(`Handling: ${task.description}`);
      // Execute task...
    }
  }
});
```

### Cost Summary

| Scale | Infrastructure | Monthly Cost |
|-------|----------------|--------------|
| 1 - 10K users | Public GUN + Google STUN | **$0** |
| 10K - 100K users | Public GUN + Google STUN | **$0** |
| 100K - 1M users | Public GUN + Google STUN | **$0** |
| 1M+ users | Public GUN + Google STUN | **$0** |
| Any scale (private) | Fly.io free tier | **$0** |
| Enterprise (dedicated) | Self-hosted VPS | $5-20 |

**Key insight:** Public infrastructure scales infinitely. You only pay if you want private/dedicated relays.

---

## Architecture

### Complete System

```
┌─────────────────────────────────────────────────────────────────────────┐
│                              Your Application                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │                      @ruvector/edge (WASM)                       │   │
│   │                                                                  │   │
│   │   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │   │
│   │   │ Identity │  │  Crypto  │  │   HNSW   │  │ Semantic │        │   │
│   │   │ Ed25519  │  │ AES-GCM  │  │  Index   │  │ Matcher  │        │   │
│   │   └──────────┘  └──────────┘  └──────────┘  └──────────┘        │   │
│   │                                                                  │   │
│   │   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │   │
│   │   │   Raft   │  │ Hybrid   │  │ Spiking  │  │Quantizer │        │   │
│   │   │Consensus │  │Post-QC   │  │ Neural   │  │Compress  │        │   │
│   │   └──────────┘  └──────────┘  └──────────┘  └──────────┘        │   │
│   │                                                                  │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│                          Transport Adapter                               │
│                                    │                                     │
│   ┌────────────────┬───────────────┼───────────────┬────────────────┐   │
│   │                │               │               │                │   │
│   ▼                ▼               ▼               ▼                ▼   │
│ WebRTC          GUN.js          libp2p          Nostr           Custom  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
         │                │                │                │
         ▼                ▼                ▼                ▼
    ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐
    │ Browser │      │ Browser │      │  Edge   │      │  Node   │
    │ Agent A │◄────►│ Agent B │◄────►│ Agent C │◄────►│ Agent D │
    └─────────┘      └─────────┘      └─────────┘      └─────────┘
                           │
                   No Central Server
                   No Cloud Costs
                   No Data Leakage
```

### What Runs Where

| Component | Runs On | Cost |
|-----------|---------|------|
| RuVector Edge (WASM) | User's browser/device | Free - their CPU |
| Vector index (HNSW) | User's browser/device | Free - their RAM |
| Encryption (AES-GCM) | User's browser/device | Free - their CPU |
| Raft consensus | Distributed across agents | Free - P2P |
| Transport (GUN/WebRTC) | P2P or free relays | Free |

---

## API Reference

### WasmIdentity
```javascript
const id = WasmIdentity.generate();
id.agent_id()           // Unique identifier
id.public_key_hex()     // Hex public key
id.sign(Uint8Array)     // Sign message
id.verify(msg, sig)     // Verify signature
```

### WasmCrypto
```javascript
const crypto = new WasmCrypto();
crypto.generate_key()            // 32-byte key
crypto.encrypt(key, plaintext)   // AES-256-GCM
crypto.decrypt(key, ciphertext)  // Decrypt
```

### WasmHnswIndex
```javascript
const index = new WasmHnswIndex(dims, m, ef);
index.insert(id, Float32Array)   // Add vector
index.search(query, k)           // Find k nearest
index.len()                      // Count
```

### WasmSemanticMatcher
```javascript
const matcher = new WasmSemanticMatcher();
matcher.register_agent(id, capabilities)
matcher.find_best_agent(task)
matcher.agent_count()
```

### WasmRaftNode
```javascript
const raft = new WasmRaftNode(id, members);
raft.start_election()    // Become candidate
raft.receive_vote(bool)  // Handle vote
raft.state()             // "follower"|"candidate"|"leader"
raft.current_term()      // Raft term number
```

### WasmHybridKeyPair
```javascript
const keys = WasmHybridKeyPair.generate();
keys.sign(message)       // Post-quantum signature
keys.verify(signature)   // Verify
keys.public_key_bytes()  // Export
```

### WasmSpikingNetwork
```javascript
const net = new WasmSpikingNetwork(in, hidden, out);
net.forward(spikes)              // Process
net.stdp_update(pre, post, lr)   // Learn
net.reset()                      // Reset state
```

### WasmQuantizer
```javascript
const q = new WasmQuantizer();
q.quantize(Float32Array)    // 4x compression
q.reconstruct(Uint8Array)   // Restore
```

### WasmAdaptiveCompressor
```javascript
const comp = new WasmAdaptiveCompressor();
comp.update_metrics(bandwidth, latency)
comp.compress(data)
comp.decompress(data)
comp.condition()  // "excellent"|"good"|"poor"|"critical"
```

---

## Performance

| Operation | Speed | Notes |
|-----------|-------|-------|
| Identity generation | 0.5ms | Ed25519 keypair |
| Sign message | 0.02ms | 50,000 ops/sec |
| AES-256-GCM encrypt | 1GB/sec | Hardware accelerated |
| HNSW search (10K vectors) | 0.1ms | 150x faster than brute |
| Semantic match | 0.5ms | LSH-based |
| Raft election | 1ms | Single round-trip |
| Quantization | 100M floats/sec | 4x compression |
| WASM load | ~50ms | 364KB binary |

---

## Security

- **Ed25519** - Elliptic curve signatures (128-bit security)
- **X25519** - Secure key exchange
- **AES-256-GCM** - Authenticated encryption
- **Post-Quantum Hybrid** - Ed25519 + Dilithium-style
- **Zero-Trust** - Verify all messages
- **Replay Protection** - Nonces and timestamps

---

## Interactive Swarm Generator

Don't know where to start? We've included an interactive code generator that helps you build swarm configurations visually. Just select your options and get production-ready code instantly.

### How to Use the Generator

```bash
# Option 1: Use a local server (recommended)
npm install @ruvector/edge
npx serve node_modules/@ruvector/edge/
# Then open http://localhost:3000/generator.html

# Option 2: Open directly in browser
# Navigate to: node_modules/@ruvector/edge/generator.html
```

The generator runs live demos directly in your browser using the actual WASM library - you can test everything before copying the code.

### What You Can Configure

**Network Topologies** - How agents connect to each other:

| Topology | Best For | Description |
|----------|----------|-------------|
| **Mesh** | General purpose | Every agent can talk to every other agent directly |
| **Star** | Centralized control | All agents connect through one coordinator |
| **Hierarchical** | Large organizations | Tree structure with managers and workers |
| **Ring** | Sequential processing | Messages pass around in a circle |
| **Gossip** | Eventual consistency | Information spreads like rumors |
| **Sharded** | Domain separation | Different groups handle different topics |

**Transport Layers** - How messages travel between agents:

| Transport | Latency | Offline? | Best For |
|-----------|---------|----------|----------|
| **GUN.js** | ~100ms | Yes | Getting started, offline-first apps |
| **WebRTC** | ~50ms | No | Real-time gaming, video, low latency |
| **libp2p** | ~200ms | Partial | IPFS integration, content addressing |
| **Nostr** | ~150ms | No | Decentralized social, simple pub/sub |

**Use Cases** - Pre-built patterns for common scenarios:

| Use Case | What It Does |
|----------|--------------|
| **AI Assistants** | Multiple specialized agents handling different types of questions |
| **Data Pipeline** | Distributed ETL with parallel processing stages |
| **Multiplayer Gaming** | Real-time game state sync with authoritative host |
| **IoT Swarm** | Coordinate sensors and actuators across locations |
| **Marketplace** | Agents that negotiate, bid, and trade autonomously |
| **Research Compute** | Distribute calculations across many devices |

**Features** - Building blocks you can mix and match:

| Feature | What It Adds |
|---------|--------------|
| **Identity** | Ed25519 cryptographic keypairs for each agent |
| **Encryption** | AES-256-GCM for all messages |
| **HNSW Index** | Fast similarity search (150x faster than brute force) |
| **Semantic Matching** | Route tasks to the best agent automatically |
| **Raft Consensus** | Elect leaders and agree on shared state |
| **Post-Quantum** | Future-proof signatures against quantum computers |
| **Spiking Neural** | Bio-inspired learning and pattern recognition |
| **Compression** | Adaptive bandwidth optimization (4-32x) |

**Exotic Patterns** - Advanced capabilities for specialized needs:

| Pattern | What It Does |
|---------|--------------|
| **MCP Tools** | Browser-based Model Context Protocol for AI collaboration |
| **Byzantine Fault** | Tolerate malicious or faulty nodes |
| **Quantum Resistant** | Hybrid signatures safe from future quantum attacks |
| **Neural Consensus** | Use spiking networks for group decisions |
| **Swarm Intelligence** | Particle swarm optimization for problem solving |
| **Self-Healing** | Automatic failure detection and recovery |
| **Emergent Behavior** | Evolutionary algorithms for agent adaptation |

### Browser-Based MCP Tools

The generator includes a complete MCP (Model Context Protocol) implementation that runs entirely in the browser. This lets you create AI tools that work with Claude and other MCP-compatible systems, but without needing a server.

```javascript
// Create a browser-based MCP server
const mcp = new BrowserMCPServer();
await mcp.init();

// Built-in tools ready to use:
// - discover_agents: Find the right agent for a task
// - send_secure_message: Encrypted P2P communication
// - store_memory: Save vectors for semantic search
// - search_memory: Find similar items by meaning
// - sign_message: Cryptographically prove authorship

// Example: Route a request to find coding help
const response = await mcp.handleRequest({
  method: 'tools/call',
  params: {
    name: 'discover_agents',
    arguments: { query: 'help me write a Python script' }
  }
});

// Connect multiple MCP servers for collaboration
const network = new MCPCollaborativeNetwork();
await network.addServer('coder', 'programming development');
await network.addServer('analyst', 'data analysis statistics');
await network.addServer('writer', 'documentation technical writing');

// Requests automatically route to the best server
const result = await network.routeRequest(request);
```

**Why browser-based MCP?**
- No server costs - runs on user devices
- Works offline - all tools available without internet
- Privacy-first - sensitive data never leaves the browser
- Instant deployment - just include the library

---

## License

MIT License - Free for commercial and personal use.

---

## Next Steps

1. **Install:** `npm install @ruvector/edge`
2. **Try the tutorial:** Build your first swarm
3. **Choose transport:** Start with GUN.js
4. **Scale:** Add more agents as needed

**Stop paying for cloud AI. Start running free edge swarms.**

[GitHub](https://github.com/ruvnet/ruvector) | [npm](https://www.npmjs.com/package/@ruvector/edge) | [Issues](https://github.com/ruvnet/ruvector/issues)