Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/npm/packages/router/README.md

@@ -0,0 +1,249 @@
+# @ruvector/router
+
+Semantic router for AI agents - vector-based intent matching with HNSW indexing and SIMD acceleration.
+
+## Features
+
+- **Semantic Intent Matching**: Route queries to intents based on meaning, not keywords
+- **HNSW Indexing**: Fast approximate nearest neighbor search
+- **SIMD Optimized**: Native Rust performance with vectorized operations
+- **Quantization**: Memory-efficient storage for large intent sets
+- **Multi-Platform**: Works on Linux, macOS, and Windows
+
+## Installation
+
+```bash
+npm install @ruvector/router
+```
+
+The package automatically installs the correct native binary for your platform.
+
+## Quick Start
+
+```typescript
+import { SemanticRouter } from '@ruvector/router';
+
+// Create router
+const router = new SemanticRouter({ dimension: 384 });
+
+// Add intents with example utterances
+router.addIntent({
+  name: 'weather',
+  utterances: [
+    'What is the weather today?',
+    'Will it rain tomorrow?',
+    'How hot will it be?'
+  ],
+  metadata: { handler: 'weather_agent' }
+});
+
+router.addIntent({
+  name: 'greeting',
+  utterances: [
+    'Hello',
+    'Hi there',
+    'Good morning',
+    'Hey'
+  ],
+  metadata: { handler: 'greeting_agent' }
+});
+
+router.addIntent({
+  name: 'help',
+  utterances: [
+    'I need help',
+    'Can you assist me?',
+    'What can you do?'
+  ],
+  metadata: { handler: 'help_agent' }
+});
+
+// Route a query
+const results = await router.route('What will the weather be like this weekend?');
+
+console.log(results[0].intent);   // 'weather'
+console.log(results[0].score);    // 0.92
+console.log(results[0].metadata); // { handler: 'weather_agent' }
+```
+
+## API Reference
+
+### `SemanticRouter`
+
+Main class for semantic routing.
+
+#### Constructor
+
+```typescript
+new SemanticRouter(config: RouterConfig)
+```
+
+**RouterConfig:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `dimension` | number | required | Embedding dimension size |
+| `metric` | string | 'cosine' | Distance metric: 'cosine', 'euclidean', 'dot' |
+| `m` | number | 16 | HNSW M parameter |
+| `efConstruction` | number | 200 | HNSW ef_construction |
+| `quantization` | boolean | false | Enable memory-efficient quantization |
+
+#### Methods
+
+##### `addIntent(intent: Intent): void`
+
+Add an intent to the router.
+
+```typescript
+router.addIntent({
+  name: 'booking',
+  utterances: ['Book a flight', 'Reserve a hotel'],
+  metadata: { department: 'travel' }
+});
+```
+
+##### `route(query: string | Float32Array, k?: number): Promise<RouteResult[]>`
+
+Route a query to matching intents.
+
+```typescript
+const results = await router.route('I want to book a vacation');
+// [{ intent: 'booking', score: 0.89, metadata: {...} }]
+```
+
+##### `routeWithEmbedding(embedding: Float32Array, k?: number): RouteResult[]`
+
+Route with a pre-computed embedding (synchronous).
+
+```typescript
+const embedding = await getEmbedding('query text');
+const results = router.routeWithEmbedding(embedding, 3);
+```
+
+##### `removeIntent(name: string): boolean`
+
+Remove an intent from the router.
+
+##### `getIntents(): string[]`
+
+Get all registered intent names.
+
+##### `clear(): void`
+
+Remove all intents.
+
+##### `save(path: string): Promise<void>`
+
+Persist router state to disk.
+
+##### `load(path: string): Promise<void>`
+
+Load router state from disk.
+
+### Types
+
+#### `Intent`
+
+```typescript
+interface Intent {
+  name: string;                        // Unique intent identifier
+  utterances: string[];                // Example utterances
+  embedding?: Float32Array | number[]; // Pre-computed embedding
+  metadata?: Record<string, unknown>;  // Custom metadata
+}
+```
+
+#### `RouteResult`
+
+```typescript
+interface RouteResult {
+  intent: string;                      // Matched intent name
+  score: number;                       // Similarity score (0-1)
+  metadata?: Record<string, unknown>;  // Intent metadata
+}
+```
+
+## Use Cases
+
+### Chatbot Intent Detection
+
+```typescript
+const router = new SemanticRouter({ dimension: 384 });
+
+// Define intents
+const intents = [
+  { name: 'faq', utterances: ['What are your hours?', 'How do I contact support?'] },
+  { name: 'order', utterances: ['Track my order', 'Where is my package?'] },
+  { name: 'return', utterances: ['I want to return this', 'How do I get a refund?'] }
+];
+
+intents.forEach(i => router.addIntent(i));
+
+// Handle user message
+async function handleMessage(text: string) {
+  const [result] = await router.route(text);
+
+  switch(result.intent) {
+    case 'faq': return handleFAQ(text);
+    case 'order': return handleOrder(text);
+    case 'return': return handleReturn(text);
+    default: return handleUnknown(text);
+  }
+}
+```
+
+### Multi-Agent Orchestration
+
+```typescript
+const agents = {
+  'code': new CodeAgent(),
+  'research': new ResearchAgent(),
+  'creative': new CreativeAgent()
+};
+
+const router = new SemanticRouter({ dimension: 768 });
+
+router.addIntent({
+  name: 'code',
+  utterances: ['Write code', 'Debug this', 'Implement a function'],
+  metadata: { agent: 'code' }
+});
+
+router.addIntent({
+  name: 'research',
+  utterances: ['Find information', 'Search for', 'Look up'],
+  metadata: { agent: 'research' }
+});
+
+// Route task to best agent
+async function routeTask(task: string) {
+  const [result] = await router.route(task);
+  const agent = agents[result.metadata.agent];
+  return agent.execute(task);
+}
+```
+
+## Platform Support
+
+| Platform | Architecture | Package |
+|----------|--------------|---------|
+| Linux | x64 | `@ruvector/router-linux-x64-gnu` |
+| Linux | ARM64 | `@ruvector/router-linux-arm64-gnu` |
+| macOS | x64 | `@ruvector/router-darwin-x64` |
+| macOS | ARM64 | `@ruvector/router-darwin-arm64` |
+| Windows | x64 | `@ruvector/router-win32-x64-msvc` |
+
+## Performance
+
+- **Routing**: < 1ms per query with HNSW
+- **Throughput**: 100,000+ routes/second
+- **Memory**: ~1KB per intent + embeddings
+
+## Related Packages
+
+- [`@ruvector/core`](https://www.npmjs.com/package/@ruvector/core) - Vector database
+- [`@ruvector/tiny-dancer`](https://www.npmjs.com/package/@ruvector/tiny-dancer) - Neural routing
+- [`@ruvector/gnn`](https://www.npmjs.com/package/@ruvector/gnn) - Graph Neural Networks
+
+## License
+
+MIT