Semantic router for AI agents - vector-based intent matching with HNSW indexing and SIMD acceleration
npm install @ruvector/routerSemantic router for AI agents - vector-based intent matching with HNSW indexing and SIMD acceleration.
- 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
``bash`
npm install @ruvector/router
The package automatically installs the correct native binary for your platform.
`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' }
`
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
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
Persist router state to disk.
##### load(path: string): Promise
Load router state from disk.
#### Intent
`typescript`
interface Intent {
name: string; // Unique intent identifier
utterances: string[]; // Example utterances
embedding?: Float32Array | number[]; // Pre-computed embedding
metadata?: Record
}
#### RouteResult
`typescript`
interface RouteResult {
intent: string; // Matched intent name
score: number; // Similarity score (0-1)
metadata?: Record
}
`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);
}
}
`
`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 | Architecture | Package |
|----------|--------------|---------|
| Linux | x64 | @ruvector/router-linux-x64-gnu |@ruvector/router-linux-arm64-gnu
| Linux | ARM64 | |@ruvector/router-darwin-x64
| macOS | x64 | |@ruvector/router-darwin-arm64
| macOS | ARM64 | |@ruvector/router-win32-x64-msvc
| Windows | x64 | |
- Routing: < 1ms per query with HNSW
- Throughput: 100,000+ routes/second
- Memory: ~1KB per intent + embeddings
- @ruvector/core - Vector database
- @ruvector/tiny-dancer - Neural routing
- @ruvector/gnn` - Graph Neural Networks
MIT